Classes
class	ComputeExposureSummaryStatsConfig

class	ComputeExposureSummaryStatsTask

Functions
	maximum_nearest_psf_distance (image_mask, psf_cat, sampling=8, bad_mask_bits=["BAD", "CR", "INTRP", "SAT", "SUSPECT", "NO_DATA", "EDGE"])

	compute_psf_image_deltas (image_mask, image_psf, sampling=96, ap_radius_pix=3.0, bad_mask_bits=["BAD", "CR", "INTRP", "SAT", "SUSPECT", "NO_DATA", "EDGE"])

	compute_ap_corr_sigma_scaled_delta (image_mask, image_ap_corr_field, psfSigma, sampling=96, bad_mask_bits=["BAD", "CR", "INTRP", "SAT", "SUSPECT", "NO_DATA", "EDGE"])

	compute_magnitude_limit (psfArea, skyBg, zeroPoint, readNoise, gain, snr)

Function Documentation

◆ compute_ap_corr_sigma_scaled_delta()

lsst.pipe.tasks.computeExposureSummaryStats.compute_ap_corr_sigma_scaled_delta	(	image_mask,
		image_ap_corr_field,
		psfSigma,
		sampling = 96,
		bad_mask_bits = ["BAD", "CR", "INTRP", "SAT", "SUSPECT", "NO_DATA", "EDGE"] )

Compute the delta between the maximum and minimum aperture correction
values scaled (divided) by ``psfSigma`` for the given field representation,
``image_ap_corr_field`` evaluated on a grid of points lying in the
unmasked region of the image.

Parameters
----------
image_mask : `lsst.afw.image.Mask`
    The mask plane associated with the exposure.
image_ap_corr_field : `lsst.afw.math.ChebyshevBoundedField`
    The ChebyshevBoundedField representation of the aperture correction
    of interest for the exposure.
psfSigma : `float`
    The PSF model second-moments determinant radius (center of chip)
    in pixels.
sampling : `int`, optional
    Sampling rate in each dimension to create the grid of points at which
    to evaluate ``image_psf``s trace radius value. The tradeoff is between
    adequate sampling versus speed.
bad_mask_bits : `list` [`str`], optional
    Mask bits required to be absent for a pixel to be considered
    "unmasked".

Returns
-------
ap_corr_sigma_scaled_delta : `float`
    The delta between the maximum and minimum of the (multiplicative)
    aperture correction values scaled (divided) by ``psfSigma`` evaluated
    on the x,y-grid subsampled on the unmasked detector pixels by a factor
    of ``sampling``.  If the aperture correction evaluates to NaN on any
    of the grid points, this is set to NaN.

Definition at line 845 of file computeExposureSummaryStats.py.

):
    """Compute the delta between the maximum and minimum aperture correction
    values scaled (divided) by ``psfSigma`` for the given field representation,
    ``image_ap_corr_field`` evaluated on a grid of points lying in the
    unmasked region of the image.
 
    Parameters
    ----------
    image_mask : `lsst.afw.image.Mask`
        The mask plane associated with the exposure.
    image_ap_corr_field : `lsst.afw.math.ChebyshevBoundedField`
        The ChebyshevBoundedField representation of the aperture correction
        of interest for the exposure.
    psfSigma : `float`
        The PSF model second-moments determinant radius (center of chip)
        in pixels.
    sampling : `int`, optional
        Sampling rate in each dimension to create the grid of points at which
        to evaluate ``image_psf``s trace radius value. The tradeoff is between
        adequate sampling versus speed.
    bad_mask_bits : `list` [`str`], optional
        Mask bits required to be absent for a pixel to be considered
        "unmasked".
 
    Returns
    -------
    ap_corr_sigma_scaled_delta : `float`
        The delta between the maximum and minimum of the (multiplicative)
        aperture correction values scaled (divided) by ``psfSigma`` evaluated
        on the x,y-grid subsampled on the unmasked detector pixels by a factor
        of ``sampling``.  If the aperture correction evaluates to NaN on any
        of the grid points, this is set to NaN.
    """
    mask_arr = image_mask.array[::sampling, ::sampling]
    bitmask = image_mask.getPlaneBitMask(bad_mask_bits)
    good = ((mask_arr & bitmask) == 0)
 
    x = np.arange(good.shape[1], dtype=np.float64) * sampling
    y = np.arange(good.shape[0], dtype=np.float64) * sampling
    xx, yy = np.meshgrid(x, y)
 
    ap_corr = image_ap_corr_field.evaluate(xx.ravel(), yy.ravel()).reshape(xx.shape)
    ap_corr_good = ap_corr[good]
    if ~np.isfinite(ap_corr_good).all():
        ap_corr_sigma_scaled_delta = float("nan")
    else:
        ap_corr_sigma_scaled_delta = (np.max(ap_corr_good) - np.min(ap_corr_good))/psfSigma
 
    return ap_corr_sigma_scaled_delta
 
 

◆ compute_magnitude_limit()

lsst.pipe.tasks.computeExposureSummaryStats.compute_magnitude_limit	(	psfArea,
		skyBg,
		zeroPoint,
		readNoise,
		gain,
		snr )

Compute the expected point-source magnitude limit at a given
signal-to-noise ratio given the exposure-level metadata. Based on
the signal-to-noise formula provided in SMTN-002 (see LSE-40 for
more details on the calculation).

  SNR = C / sqrt( C/g + (B/g + sigma_inst**2) * neff )

where C is the counts from the source, B is counts from the (sky)
background, sigma_inst is the instrumental (read) noise, neff is
the effective size of the PSF, and g is the gain in e-/ADU.  Note
that input values of ``skyBg``, ``zeroPoint``, and ``readNoise``
should all consistently be in electrons or ADU.

Parameters
----------
psfArea : `float`
    The effective area of the PSF [pix].
skyBg : `float`
    The sky background counts for the exposure [ADU or e-].
zeroPoint : `float`
    The zeropoint (includes exposure time) [ADU or e-].
readNoise : `float`
    The instrumental read noise for the exposure [ADU or e-].
gain : `float`
    The instrumental gain for the exposure [e-/ADU]. The gain should
     be 1.0 if the skyBg, zeroPoint, and readNoise are in e-.
snr : `float`
    Signal-to-noise ratio at which magnitude limit is calculated.

Returns
-------
magnitude_limit : `float`
    The expected magnitude limit at the given signal to noise.

Definition at line 902 of file computeExposureSummaryStats.py.

):
    """Compute the expected point-source magnitude limit at a given
    signal-to-noise ratio given the exposure-level metadata. Based on
    the signal-to-noise formula provided in SMTN-002 (see LSE-40 for
    more details on the calculation).
 
      SNR = C / sqrt( C/g + (B/g + sigma_inst**2) * neff )
 
    where C is the counts from the source, B is counts from the (sky)
    background, sigma_inst is the instrumental (read) noise, neff is
    the effective size of the PSF, and g is the gain in e-/ADU.  Note
    that input values of ``skyBg``, ``zeroPoint``, and ``readNoise``
    should all consistently be in electrons or ADU.
 
    Parameters
    ----------
    psfArea : `float`
        The effective area of the PSF [pix].
    skyBg : `float`
        The sky background counts for the exposure [ADU or e-].
    zeroPoint : `float`
        The zeropoint (includes exposure time) [ADU or e-].
    readNoise : `float`
        The instrumental read noise for the exposure [ADU or e-].
    gain : `float`
        The instrumental gain for the exposure [e-/ADU]. The gain should
         be 1.0 if the skyBg, zeroPoint, and readNoise are in e-.
    snr : `float`
        Signal-to-noise ratio at which magnitude limit is calculated.
 
    Returns
    -------
    magnitude_limit : `float`
        The expected magnitude limit at the given signal to noise.
 
    """
    # Effective number of pixels within the PSF calculated directly
    # from the PSF model.
    neff = psfArea
 
    # Instrumental noise (read noise only)
    sigma_inst = readNoise
 
    # Total background counts derived from Eq. 45 of LSE-40
    background = (skyBg/gain + sigma_inst**2) * neff
    # Source counts to achieve the desired SNR (from quadratic formula)
    source = (snr**2)/(2*gain) + np.sqrt((snr**4)/(4*gain) + snr**2 * background)
 
    # Convert to a magnitude using the zeropoint.
    # Note: Zeropoint currently includes exposure time
    magnitude_limit = -2.5*np.log10(source) + zeroPoint
 
    return magnitude_limit

◆ compute_psf_image_deltas()

lsst.pipe.tasks.computeExposureSummaryStats.compute_psf_image_deltas	(	image_mask,
		image_psf,
		sampling = 96,
		ap_radius_pix = 3.0,
		bad_mask_bits = ["BAD", "CR", "INTRP", "SAT", "SUSPECT", "NO_DATA", "EDGE"] )

Compute the delta between the maximum and minimum model PSF trace radius
values evaluated on a grid of points lying in the unmasked region of the
image.

Parameters
----------
image_mask : `lsst.afw.image.Mask`
    The mask plane associated with the exposure.
image_psf : `lsst.afw.detection.Psf`
    The PSF model associated with the exposure.
sampling : `int`, optional
    Sampling rate in each dimension to create the grid of points at which
    to evaluate ``image_psf``s trace radius value. The tradeoff is between
    adequate sampling versus speed.
ap_radius_pix : `float`, optional
    Radius in pixels of the aperture on which to measure the flux of the
    PSF model.
bad_mask_bits : `list` [`str`], optional
    Mask bits required to be absent for a pixel to be considered
    "unmasked".

Returns
-------
psf_trace_radius_delta, psf_ap_flux_delta : `float`
    The delta (in pixels) between the maximum and minimum model PSF trace
    radius values and the PSF aperture fluxes (with aperture radius of
    max(2, 3*psfSigma)) evaluated on the x,y-grid subsampled on the
    unmasked detector pixels by a factor of ``sampling``.  If both the
    model PSF trace radius value and aperture flux value on the grid
    evaluate to NaN, then NaNs are returned immediately.

Definition at line 777 of file computeExposureSummaryStats.py.

):
    """Compute the delta between the maximum and minimum model PSF trace radius
    values evaluated on a grid of points lying in the unmasked region of the
    image.
 
    Parameters
    ----------
    image_mask : `lsst.afw.image.Mask`
        The mask plane associated with the exposure.
    image_psf : `lsst.afw.detection.Psf`
        The PSF model associated with the exposure.
    sampling : `int`, optional
        Sampling rate in each dimension to create the grid of points at which
        to evaluate ``image_psf``s trace radius value. The tradeoff is between
        adequate sampling versus speed.
    ap_radius_pix : `float`, optional
        Radius in pixels of the aperture on which to measure the flux of the
        PSF model.
    bad_mask_bits : `list` [`str`], optional
        Mask bits required to be absent for a pixel to be considered
        "unmasked".
 
    Returns
    -------
    psf_trace_radius_delta, psf_ap_flux_delta : `float`
        The delta (in pixels) between the maximum and minimum model PSF trace
        radius values and the PSF aperture fluxes (with aperture radius of
        max(2, 3*psfSigma)) evaluated on the x,y-grid subsampled on the
        unmasked detector pixels by a factor of ``sampling``.  If both the
        model PSF trace radius value and aperture flux value on the grid
        evaluate to NaN, then NaNs are returned immediately.
    """
    psf_trace_radius_list = []
    psf_ap_flux_list = []
    mask_arr = image_mask.array[::sampling, ::sampling]
    bitmask = image_mask.getPlaneBitMask(bad_mask_bits)
    good = ((mask_arr & bitmask) == 0)
 
    x = np.arange(good.shape[1]) * sampling
    y = np.arange(good.shape[0]) * sampling
    xx, yy = np.meshgrid(x, y)
 
    for x_mesh, y_mesh, good_mesh in zip(xx, yy, good):
        for x_point, y_point, is_good in zip(x_mesh, y_mesh, good_mesh):
            if is_good:
                position = geom.Point2D(x_point, y_point)
                psf_trace_radius = image_psf.computeShape(position).getTraceRadius()
                psf_ap_flux = image_psf.computeApertureFlux(ap_radius_pix, position)
                if ~np.isfinite(psf_trace_radius) and ~np.isfinite(psf_ap_flux):
                    return float("nan"), float("nan")
                psf_trace_radius_list.append(psf_trace_radius)
                psf_ap_flux_list.append(psf_ap_flux)
 
    psf_trace_radius_delta = np.max(psf_trace_radius_list) - np.min(psf_trace_radius_list)
    if np.any(np.asarray(psf_ap_flux_list) < 0.0):  # Consider any -ve flux entry as "bad".
        psf_ap_flux_delta = float("nan")
    else:
        psf_ap_flux_delta = np.max(psf_ap_flux_list) - np.min(psf_ap_flux_list)
 
    return psf_trace_radius_delta, psf_ap_flux_delta
 
 

◆ maximum_nearest_psf_distance()

lsst.pipe.tasks.computeExposureSummaryStats.maximum_nearest_psf_distance	(	image_mask,
		psf_cat,
		sampling = 8,
		bad_mask_bits = ["BAD", "CR", "INTRP", "SAT", "SUSPECT", "NO_DATA", "EDGE"] )

Compute the maximum distance of an unmasked pixel to its nearest PSF.

Parameters
----------
image_mask : `lsst.afw.image.Mask`
    The mask plane associated with the exposure.
psf_cat : `lsst.afw.table.SourceCatalog` or `astropy.table.Table`
    Catalog containing only the stars used in the PSF modeling.
sampling : `int`
    Sampling rate in each dimension to create the grid of points on which
    to evaluate the distance to the nearest PSF star. The tradeoff is
    between adequate sampling versus speed.
bad_mask_bits : `list` [`str`]
    Mask bits required to be absent for a pixel to be considered
    "unmasked".

Returns
-------
max_dist_to_nearest_psf : `float`
    The maximum distance (in pixels) of an unmasked pixel to its nearest
    PSF model star.

Definition at line 730 of file computeExposureSummaryStats.py.

):
    """Compute the maximum distance of an unmasked pixel to its nearest PSF.
 
    Parameters
    ----------
    image_mask : `lsst.afw.image.Mask`
        The mask plane associated with the exposure.
    psf_cat : `lsst.afw.table.SourceCatalog` or `astropy.table.Table`
        Catalog containing only the stars used in the PSF modeling.
    sampling : `int`
        Sampling rate in each dimension to create the grid of points on which
        to evaluate the distance to the nearest PSF star. The tradeoff is
        between adequate sampling versus speed.
    bad_mask_bits : `list` [`str`]
        Mask bits required to be absent for a pixel to be considered
        "unmasked".
 
    Returns
    -------
    max_dist_to_nearest_psf : `float`
        The maximum distance (in pixels) of an unmasked pixel to its nearest
        PSF model star.
    """
    mask_arr = image_mask.array[::sampling, ::sampling]
    bitmask = image_mask.getPlaneBitMask(bad_mask_bits)
    good = ((mask_arr & bitmask) == 0)
 
    x = np.arange(good.shape[1]) * sampling
    y = np.arange(good.shape[0]) * sampling
    xx, yy = np.meshgrid(x, y)
 
    dist_to_nearest_psf = np.full(good.shape, np.inf)
    for psf in psf_cat:
        x_psf = psf["slot_Centroid_x"]
        y_psf = psf["slot_Centroid_y"]
        dist_to_nearest_psf = np.minimum(dist_to_nearest_psf, np.hypot(xx - x_psf, yy - y_psf))
        unmasked_dists = dist_to_nearest_psf * good
        max_dist_to_nearest_psf = np.max(unmasked_dists)
 
    return max_dist_to_nearest_psf
 
 

Classes

Functions

Function Documentation

◆ compute_ap_corr_sigma_scaled_delta()

◆ compute_magnitude_limit()

◆ compute_psf_image_deltas()

◆ maximum_nearest_psf_distance()