LSST Applications g063fba187b+fee0456c91,g0f08755f38+ea96e5a5a3,g1653933729+a8ce1bb630,g168dd56ebc+a8ce1bb630,g1a2382251a+90257ff92a,g20f6ffc8e0+ea96e5a5a3,g217e2c1bcf+937a289c59,g28da252d5a+daa7da44eb,g2bbee38e9b+253935c60e,g2bc492864f+253935c60e,g3156d2b45e+6e55a43351,g32e5bea42b+31359a2a7a,g347aa1857d+253935c60e,g35bb328faa+a8ce1bb630,g3a166c0a6a+253935c60e,g3b1af351f3+a8ce1bb630,g3e281a1b8c+c5dd892a6c,g414038480c+416496e02f,g41af890bb2+afe91b1188,g599934f4f4+0db33f7991,g7af13505b9+e36de7bce6,g80478fca09+da231ba887,g82479be7b0+a4516e59e3,g858d7b2824+ea96e5a5a3,g89c8672015+f4add4ffd5,g9125e01d80+a8ce1bb630,ga5288a1d22+bc6ab8dfbd,gb58c049af0+d64f4d3760,gc28159a63d+253935c60e,gcab2d0539d+3f2b72788c,gcf0d15dbbd+4ea9c45075,gda6a2b7d83+4ea9c45075,gdaeeff99f8+1711a396fd,ge79ae78c31+253935c60e,gef2f8181fd+3031e3cf99,gf0baf85859+c1f95f4921,gfa517265be+ea96e5a5a3,gfa999e8aa5+17cd334064,w.2024.50
LSST Data Management Base Package
Loading...
Searching...
No Matches
Functions
lsst.meas.algorithms.variance_plane Namespace Reference

Functions

 remove_signal_from_variance (exposure, gain=None, gains=None, average_across_amps=False, in_place=False)
 

Detailed Description

Utility functions related to the variance plane of Exposure objects. Tested
in `ip_isr/tests/test_variance_plane.py` to avoid circular dependencies.

Function Documentation

◆ remove_signal_from_variance()

lsst.meas.algorithms.variance_plane.remove_signal_from_variance ( exposure,
gain = None,
gains = None,
average_across_amps = False,
in_place = False )
Removes the Poisson contribution from actual sources in the variance plane
of an Exposure.

If neither gain nor gains are provided, the function estimates the gain(s).
If ``average_across_amps`` is True, a single gain value for the entire
image is estimated. If False, individual gain values for each amplifier are
estimated. The estimation involves a linear fit of variance versus image
plane.

Parameters
----------
exposure : `~lsst.afw.image.Exposure`
    The background-subtracted exposure containing a variance plane to be
    corrected for source contributions.
gain : `float`, optional
    The gain value for the entire image. This parameter is used if
    ``gains`` is not provided. If both ``gain`` and ``gains`` are None, and
    ``average_across_amps`` is True, ``gain`` is estimated from the image
     and variance planes.
gains : dict[`str`, `float`], optional
    A dictionary mapping amplifier ID (as a string) to gain value. This
    parameter is used if ``gain`` is not provided. If both ``gain`` and
    ``gains`` are None, and ``average_across_amps`` is False, ``gains`` are
    estimated from the image and variance planes.
average_across_amps : `bool`, optional
    Determines the gain estimation strategy. If True, the gain for the
    entire image is estimated at once. If False, individual gains for each
    amplifier are estimated. This parameter is ignored if either ``gain``
    or ``gains`` is specified.
in_place : `bool`, optional
    If True, the variance plane of the input Exposure is modified in place.
    A modified copy of the variance plane is always returned irrespective
    of this.

Returns
-------
variance_plane : `~lsst.afw.image.Image`
    The corrected variance plane, with the signal contribution removed.

Raises
------
AttributeError
    If amplifiers cannot be retrieved from the exposure.
ValueError
    If both ``gain`` and ``gains`` are provided, or if the number of
    provided ``gains`` does not match the number of amplifiers.

Definition at line 31 of file variance_plane.py.

31def remove_signal_from_variance(exposure, gain=None, gains=None, average_across_amps=False, in_place=False):
32 """
33 Removes the Poisson contribution from actual sources in the variance plane
34 of an Exposure.
35
36 If neither gain nor gains are provided, the function estimates the gain(s).
37 If ``average_across_amps`` is True, a single gain value for the entire
38 image is estimated. If False, individual gain values for each amplifier are
39 estimated. The estimation involves a linear fit of variance versus image
40 plane.
41
42 Parameters
43 ----------
44 exposure : `~lsst.afw.image.Exposure`
45 The background-subtracted exposure containing a variance plane to be
46 corrected for source contributions.
47 gain : `float`, optional
48 The gain value for the entire image. This parameter is used if
49 ``gains`` is not provided. If both ``gain`` and ``gains`` are None, and
50 ``average_across_amps`` is True, ``gain`` is estimated from the image
51 and variance planes.
52 gains : dict[`str`, `float`], optional
53 A dictionary mapping amplifier ID (as a string) to gain value. This
54 parameter is used if ``gain`` is not provided. If both ``gain`` and
55 ``gains`` are None, and ``average_across_amps`` is False, ``gains`` are
56 estimated from the image and variance planes.
57 average_across_amps : `bool`, optional
58 Determines the gain estimation strategy. If True, the gain for the
59 entire image is estimated at once. If False, individual gains for each
60 amplifier are estimated. This parameter is ignored if either ``gain``
61 or ``gains`` is specified.
62 in_place : `bool`, optional
63 If True, the variance plane of the input Exposure is modified in place.
64 A modified copy of the variance plane is always returned irrespective
65 of this.
66
67 Returns
68 -------
69 variance_plane : `~lsst.afw.image.Image`
70 The corrected variance plane, with the signal contribution removed.
71
72 Raises
73 ------
74 AttributeError
75 If amplifiers cannot be retrieved from the exposure.
76 ValueError
77 If both ``gain`` and ``gains`` are provided, or if the number of
78 provided ``gains`` does not match the number of amplifiers.
79 """
80 variance_plane = exposure.variance if in_place else exposure.variance.clone()
81 if gain is None and gains is None:
82 if average_across_amps:
83 amp_bboxes = [exposure.getBBox()]
84 else:
85 try:
86 amps = exposure.getDetector().getAmplifiers()
87 amp_bboxes = [amp.getBBox() for amp in amps]
88 except AttributeError:
89 raise AttributeError(
90 "Could not retrieve amplifiers from exposure. To compute a simple gain value across the "
91 "entire image, use average_across_amps=True."
92 )
93 # Fit a straight line to variance vs (sky-subtracted) signal. Then
94 # evaluate that line at zero signal to get an estimate of the
95 # signal-free variance.
96 for amp_bbox in amp_bboxes:
97 amp_im_arr = exposure[amp_bbox].image.array
98 amp_var_arr = variance_plane[amp_bbox].array
99 good = (amp_var_arr != 0) & np.isfinite(amp_var_arr) & np.isfinite(amp_im_arr)
100 fit = np.polyfit(amp_im_arr[good], amp_var_arr[good], deg=1)
101 # Fit is [1/gain, sky_var].
102 amp_gain = 1.0 / fit[0]
103 variance_plane[amp_bbox].array[good] -= amp_im_arr[good] / amp_gain
104 elif gain is None and gains is not None:
105 amps = exposure.getDetector().getAmplifiers()
106 namps = len(amps)
107 if len(gains) != namps:
108 raise ValueError(
109 f"Incorrect number of gains provided: {len(gains)} values for {namps} amplifiers."
110 )
111 for amp in amps:
112 amp_bbox = amp.getBBox()
113 amp_gain = gains[amp.getName()]
114 im_arr = exposure[amp_bbox].image.array
115 variance_plane[amp_bbox].array -= im_arr / amp_gain
116 elif gain is not None and gains is None:
117 im_arr = exposure.image.array
118 variance_plane.array -= im_arr / gain
119 elif gain is not None and gains is not None:
120 raise ValueError(
121 "Both 'gain' and 'gains' are provided. Please provide only one of them or none at "
122 "all in case of automatic gain estimation from the image and variance planes."
123 )
124 # Check that the variance plane has no negative values.
125 if np.any(variance_plane.array < 0):
126 raise ValueError("Corrected variance plane has negative values.")
127 return variance_plane