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 (arraylike) – A 2D image containing the sources of interest. The image must already be backgroundsubtracted.
 segmap (arraylike (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 (arraylike (bool), optional) – A 2D array with the same size as
image
, where pixels set toTrue
are ignored from all calculations.  weightmap (arraylike, 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 sigmaimage) using Poisson statistics.
This parameter is only used when
weightmap
is not provided.  psf (arraylike, 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 toeta
. 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 basinhopping stage of the maximization. A value of at least 100 is recommended for “production” runs, but it can be timeconsuming. 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 isFalse
.
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 secondorder moments as) the source, relative to the point that minimizes the asymmetry.

ellipticity_centroid
¶ The ellipticity of (the Gaussian function that has the same secondorder moments as) the source, relative to the centroid.

elongation_asymmetry
¶ The elongation of (the Gaussian function that has the same secondorder moments as) the source, relative to the point that minimizes the asymmetry.

elongation_centroid
¶ The elongation of (the Gaussian function that has the same secondorder 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 GiniM20 bulge statistic, F(G, M20), as defined in RodriguezGomez et al. (2019).

gini_m20_merger
¶ Return the GiniM20 merger statistic, S(G, M20), as defined in RodriguezGomez 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 sizeindependent 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 bruteforce search over a relatively coarse array of quantiles, as in the original implementation, followed by a finer search using the basinhopping 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 (halflight) 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 (halflight) 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 xcoordinate of the center of the 2D Sersic fit (astropy.modeling.models.Sersic2D), relative to the original image.

sersic_yc
¶ The ycoordinate 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 signaltonoise per pixel using the Petrosian segmap.

xc_asymmetry
¶ The xcoordinate of the point that minimizes the asymmetry, relative to the original image.

xc_centroid
¶ The xcoordinate 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 ycoordinate of the point that minimizes the asymmetry, relative to the original image.

yc_centroid
¶ The ycoordinate 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 bysegmap
.Parameters:  image (arraylike) – A 2D image containing the sources of interest. The image must already be backgroundsubtracted.
 segmap (arraylike (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.