API Reference

class statmorph.SourceMorphology(image, segmap, label, mask=None, weightmap=None, gain=None, psf=None, cutout_extent=1.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_maxiter=500, 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.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 in principle 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_maxiter (int, optional) – The maximum number of iterations during the Sersic profile fitting.
  • segmap_overlap_ratio (float, optional) – The minimum ratio between the area of the intersection of all 3 segmaps and the area of the largest segmap in order to have a good measurement.
  • verbose (bool, optional) – If True, this prints various minor warnings (which do not set off the “bad measurement” flag) during the calculations. The default value is False.

References

See README.rst for a list of references.

asymmetry

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

concentration

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

deviation

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

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.

ellipticity_centroid

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

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.

elongation_centroid

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

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.

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”.

gini

Calculate the Gini coefficient as described in Lotz et al. (2004).

gini_m20_bulge

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

gini_m20_merger

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

intensity

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

m20

Calculate the M_20 coefficient as described in Lotz et al. (2004).

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.

nx_stamp

Number of pixels in the ‘postage stamp’ along the x direction.

ny_stamp

Number of pixels in the ‘postage stamp’ along the y direction.

orientation_asymmetry

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

orientation_centroid

The orientation (in radians) of the source, relative to the centroid.

outer_asymmetry

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

r20

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

r50

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

r80

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

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.

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.

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).

rmax_ellip

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

rpetro_circ

Calculate the Petrosian radius with respect to the point that minimizes the asymmetry.

rpetro_ellip

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

sersic_amplitude

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

sersic_ellip

The ellipticity of the 2D Sersic fit (astropy.modeling.models.Sersic2D).

sersic_n

The Sersic index n (astropy.modeling.models.Sersic2D).

sersic_rhalf

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

sersic_theta

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

sersic_xc

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

sersic_yc

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

shape_asymmetry

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

sky_mean

Mean background value. Equal to -99.0 when there is no skybox.

sky_median

Median background value. Equal to -99.0 when there is no skybox.

sky_sigma

Standard deviation of the background. Equal to -99.0 when there is no skybox.

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.

sn_per_pixel

Calculate the signal-to-noise per pixel using the Petrosian segmap.

xc_asymmetry

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

xc_centroid

The x-coordinate of the centroid, relative to the original image.

xmax_stamp

The maximum x position of the ‘postage stamp’.

xmin_stamp

The minimum x position of the ‘postage stamp’.

yc_asymmetry

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

yc_centroid

The y-coordinate of the centroid, relative to the original image.

ymax_stamp

The maximum y position of the ‘postage stamp’.

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.SegmentationImage) – A 2D segmentation map where different sources are labeled with different positive integer values. A value of zero is reserved for the background.
Other Parameters:
 

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

See also

SourceMorphology()
Class to measure morphological parameters.

Examples

See README.rst for usage examples.

References

See README.rst for a list of references.