ImageDepth#

class photutils.utils.ImageDepth(aper_radius, *, n_sigma=5.0, mask_pad=0, n_apertures=1000, n_iters=10, overlap=True, overlap_maxiters=100, seed=None, zeropoint=0.0, sigma_clip=<default: SigmaClip(sigma=3.0, maxiters=10)>, progress_bar=True)[source]#

Bases: object

Class to calculate the limiting flux and magnitude of an image.

Parameters:

aper_radiusfloat: The radius (in pixels) of the circular apertures used to compute the image depth.
n_sigmafloat, optional: The number of standard deviations at which to compute the image depths.

Deprecated since version 3.0: The nsigma keyword is deprecated. Use n_sigma instead.
mask_padfloat, optional: An additional padding (in pixels) to apply when dilating the input mask.
n_aperturesint, optional: The number of circular apertures used to compute the image depth.

Deprecated since version 3.0: The napers keyword is deprecated. Use n_apertures instead.
n_itersint, optional: The number of iterations, each with randomly-generated apertures, for which the image depth will be calculated.

Deprecated since version 3.0: The niters keyword is deprecated. Use n_iters instead.
overlapbool, optional: Whether to allow the apertures to overlap.
overlap_maxitersint, optional: The maximum number of iterations that will be used when attempting to find additional non-overlapping apertures. This keyword has no effect unless overlap=False. While increasing this number may generate more non-overlapping apertures in crowded cases, it will also run slower.
seedint, optional: A seed to initialize the numpy.random.BitGenerator. If None, then fresh, unpredictable entropy will be pulled from the OS. Separate function calls with the same seed will generate the same results.
zeropointfloat, optional: The zeropoint used to calculate the magnitude limit from the flux limit:

\[m_{\mathrm{lim}} = -2.5 \log_{10} f_{\mathrm{lim}} + \mathrm{zeropoint}\]
sigma_clipastropy.stats.SigmaClip, optional: A SigmaClip object that defines the sigma clipping parameters to use when computing the limiting flux. If None then no sigma clipping will be performed.
progress_barbool, optional: Whether to display a progress bar. The progress bar requires that the tqdm optional dependency be installed.

Attributes:

apertureslist of CircularAperture: A list of circular apertures for each iteration.
napers_used1D ndarray: Deprecated since version 3.0: Use n_apertures_used instead.
n_apertures_used1D ndarray: An array of the number of apertures used for each iteration.
fluxeslist of ndarray: A list of arrays containing the flux measurements for each iteration.
flux_limits1D ndarray: An array of the flux limits for each iteration.
mag_limits1D ndarray: An array of the magnitude limits for each iteration.

Notes

The image depth is calculated by placing random circular apertures with the specified radius on blank regions of the image. The number of apertures is specified by the n_apertures keyword. The blank regions are calculated from an input mask, which should mask both sources in the image and areas without image coverage. The input mask will be dilated with a circular footprint with a radius equal to the input aper_radius plus mask_pad. The image border is also masked with the same radius.

The flux limit is calculated as the standard deviation of the aperture fluxes times the input n_sigma significance level. The aperture flux values can be sigma clipped prior to computing the standard deviation using the sigma_clip keyword.

The flux limit is calculated n_iters times, each with a randomly-generated set of circular apertures. The returned flux limit is the average of these flux limits.

The magnitude limit is calculated from flux limit using the input zeropoint keyword as:

\[m_{\mathrm{lim}} = -2.5 \log_{10} f_{\mathrm{lim}} + \mathrm{zeropoint}\]

Examples

>>> from astropy.convolution import convolve
>>> from astropy.visualization import simple_norm
>>> from photutils.datasets import make_100gaussians_image
>>> from photutils.segmentation import SourceFinder, make_2dgaussian_kernel
>>> from photutils.utils import ImageDepth
>>> bkg = 5.0
>>> data = make_100gaussians_image() - bkg
>>> kernel = make_2dgaussian_kernel(3.0, size=5)
>>> convolved_data = convolve(data, kernel)
>>> n_pixels = 10
>>> threshold = 3.2
>>> finder = SourceFinder(n_pixels=n_pixels, progress_bar=False)
>>> segment_map = finder(convolved_data, threshold)
>>> mask = segment_map.make_source_mask()
>>> radius = 4
>>> depth = ImageDepth(radius, n_sigma=5.0, n_apertures=500,
...                    n_iters=2, mask_pad=5, overlap=False,
...                    seed=123, zeropoint=23.9,
...                    progress_bar=False)
>>> limits = depth(data, mask)
>>> print(np.array(limits))
[68.7403149  19.30697121]

# Plot the random apertures for the first iteration

import matplotlib.pyplot as plt
from astropy.convolution import convolve
from astropy.visualization import simple_norm
from photutils.datasets import make_100gaussians_image
from photutils.segmentation import SourceFinder, make_2dgaussian_kernel
from photutils.utils import ImageDepth

bkg = 5.0
data = make_100gaussians_image() - bkg
kernel = make_2dgaussian_kernel(3.0, size=5)
convolved_data = convolve(data, kernel)
n_pixels = 10
threshold = 3.2
finder = SourceFinder(n_pixels=n_pixels, progress_bar=False)
segment_map = finder(convolved_data, threshold)
mask = segment_map.make_source_mask()
radius = 4
depth = ImageDepth(radius, n_sigma=5.0, n_apertures=500,
                   n_iters=2, overlap=False, seed=123,
                   progress_bar=False)
limits = depth(data, mask)

fig, ax = plt.subplots(nrows=2, figsize=(5, 7))
norm = simple_norm(data, 'sqrt', percent=99.5)
ax[0].imshow(data, norm=norm, origin='lower')
color = 'white'
depth.apertures[0].plot(ax=ax[0], color=color)
ax[0].set_title('Data with blank apertures')
ax[1].imshow(mask, origin='lower')
depth.apertures[0].plot(ax=ax[1], color=color)
ax[1].set_title('Mask with blank apertures')

fig.tight_layout()

(Source code, png, hires.png, pdf, svg)

../_images/photutils-utils-ImageDepth-1.png

Methods Summary

__call__(data, mask)

Calculate the limiting flux and magnitude of an image.

Methods Documentation

__call__(data, mask)[source]#

Calculate the limiting flux and magnitude of an image.

Parameters:

data2D ndarray: The 2D array, which should be in flux units (not surface brightness units).
mask2D bool ndarray: A 2D mask array with the same shape as data where a True value indicates the corresponding element of data is masked. The input array should mask both sources (e.g., from a segmentation image) and regions without image coverage. If None, then the entire image will be used.

Returns:

flux_limit, mag_limitfloat: The flux and magnitude limits. The flux limit is returned in the same units as the input data. The magnitude limit is calculated from the flux limit and the input zeropoint.