metrics#

Methods for computing performance metrics (e.g., SNR, logFPF, …).

hsr4hci.metrics.compute_metrics(frame, polar_position, aperture_radius, planet_mode='FS', noise_mode='P', search_radius=Quantity(1, 'pixel'), exclusion_angle=None, n_rotation_steps=100)[source]#

Compute evaluation metrics (SNR, FPF, …) at a given position.

Parameters:

  • frame (ndarray) – The frame (usually a signal estimate) on which to compute the metrics.

  • polar_position (Tuple[Quantity, Quantity]) – The position of the (candidate) planet as a 2-tuple (separation, angle) using “astronomical” polar coordinates (i.e., 0 degrees = North = “up”, not “right”, as in mathematical polar coordinates).

  • aperture_radius (Quantity) – If the planet_mode or noise_mode is aperture-based, this parameter controls the size of the apertures. Regardless of the mode, this value is required to determine the number of reference positions; therefore it cannot be optional. (Usually set this to 1/2 of the FWHM of the PSF.)

  • planet_mode (str) – The mode to be used to measure the flux of the planet, or signal. See hsr4hci.photometry.get_flux() for more details.

  • noise_mode (str) – The mode to be used to measure the flux at the reference positions. See hsr4hci.photometry.get_flux() for more details. Note that this should be compatible with the choice for the planet_mode, meaning that if the mode for the planet is “FS”, the mode for the noise should be “P”, and if the planet mode is “ASS”, the noise mode should be “AS”.

  • search_radius (Optional[Quantity]) – If the planet_mode is search-based (“ASS” or “FS”), this parameter controls how big the area is that should be considered for maximizing the planet flux.

  • exclusion_angle (Optional[Quantity]) – This parameter controls how the reference positions are chosen. It can be used, for example, to exclude the reference positions immediately to the left and right of the planet position, because for some algorithms (e.g., PCA), these are known to contain self-subtraction / over-subtraction “wings” which do not give an unbiased estimate of the background. For more details, see hsr4hci.positions.get_reference_positions().

  • n_rotation_steps (int) – This parameter determines the number of rotation steps that are applied to the reference positions: The exact placement of the reference positions is always somewhat arbitrary, but can have a rather large effect on the final metrics. By rotating the reference positions, we can at least get a feeling for the size of the effect. See hsr4hci.positions.rotate_reference_positions() for more details. If this value is set to 0, no rotations are performed.

Returns:

A 2-tuple, consisting of

  1. A (nested) dictionary containing the mean, median, standard deviation, minimum and maximum of each metric (signal, noise, snr, fpf, log_fpf, p_value), and

  2. A (nested) dictionary containing the position of the planet before and after a potential optimization, both in polar and in Cartesian coordinates.

Return type:

Tuple[Dict[str, Dict[str, float]], Dict[str, Dict[str, Any]]]

hsr4hci.metrics.two_sample_t_test(planet_samples, noise_samples)[source]#

Compute the two-sample t-test that is the basis of the signal-to-noise (SNR) as introduced by the following paper:

Mawet, D. et al. (2014): “Fundamental limitations of high contrast imaging set by small sample statistics”. The Astrophysical Journal, 792(2), 97. DOI: 10.1088/0004-637X/792/2/97

Parameters:

  • planet_samples (Union[List[float], ndarray]) – A list of floats containing the results of the flux measurements at the planet position(s). Generally, in almost all cases, there is only a single planet position and, therefore, only a single planet sample.

  • noise_samples (Union[List[float], ndarray]) – A list of floats containing the results of the flux measurements at the reference (or noise) positions.

Returns:

A 5-tuple consisting of

  1. signal: The numerator of the SNR.

  2. noise: The denominator of the SNR.

  3. snr: The signal-to-noise ratio, that is, the test statistic of the \(t\)-test that is being performed by this function (see paper for details).

  4. fpf: The false positive fraction, which is computed from the SNR using the survival function of a \(t\)-distribution.

  5. p_value: The FPF converted to a \(p\)-value using the CDF of a \(t\)-distribution.

Return type:

Tuple[float, float, float, float, float]