contrast#

Methods for estimating contrasts, flux ratios and throughputs, as well as computing contrast curves (i.e., detection limits).

hsr4hci.contrast.get_contrast(signal_estimate, polar_position, psf_template, metadata, no_fake_planets=None, expected_contrast=None, planet_mode='FS', noise_mode='P', exclusion_angle=None)[source]#

Compute the contrast and flux ratio for the planet at the given polar_position in the signal_estimate, and, if desired, also compute the throughput (i.e., the ratio of the observed and the expected flux ratio).

Parameters:

  • signal_estimate (ndarray) – A 2D numpy array with the signal estimate.

  • polar_position (Tuple[Quantity, Quantity]) – A 2-tuple of (separation, angle), specifying the position of the planet for which to compute the contrast and flux ratio.

  • psf_template (ndarray) – A 2D numpy array containing the unsaturated (!) and unnormalized (!) PSF template for the data set on which the signal_estimate was obtained.

  • metadata (dict) – A dictionary containing metadata about the data set. Requires the following keys to compute the stellar flux: "DIT_STACK", "DIT_PSF_TEMPLATE" and "ND_FILTER".

  • no_fake_planets (Optional[ndarray]) – Optionally, a 2D numpy array with the same shape as the signal_estimate If you want to compute the contrast using the “classic” approach, you can use this argument to pass a signal estimate that was obtained on the data set without any planets. This array will be subtracted from the signal estimate before measuring the planet flux.

  • expected_contrast (Optional[float]) – Optionally, a float containing the expected contrast in magnitudes. If this value is given, the throughput is computed (otherwise the throughput is NaN).

  • planet_mode (str) – Photometry mode that is used to measure the planet flux. See also hsr4hci.photometry.get_flux() for details.

  • noise_mode (str) – Photometry mode that is used to measure the flux at the reference positions. See also hsr4hci.photometry.get_flux() for details.

  • exclusion_angle (Optional[Quantity]) – Exclusion angle that is used for determining the reference positions (basically: whether to ignore the positions left and right of the polar_position which may contain self-subtraction “wings”). For more details, see hsr4hci.positions.get_reference_positions(). This option is only used if no_fake_planets is None.

Returns:

A dictionary containing the observed contrast and flux ratio, the expected contrast and flux ratio, the throughput, the raw flux and the background flux, the stellar flux, and the (optimized) Cartesian position of the planet candidate.

Return type:

dict

hsr4hci.contrast.get_contrast_curve(df, sigma_threshold=5, log_transform=True, aggregation_function=np.median)[source]#

Given a pandas data frame df with experiment results, compute a contrast curve, that is, for each separation, determine the contrast value until which we can detect a planet with a confidence that matches the given sigma_threshold.

Parameters:

  • df (DataFrame) – A pandas data frame with experiment results. In particular, we need columns for the contrast, the separation and the false positive fraction (FPF).

  • sigma_threshold (float) – The significance threshold for what we still want to accept as “detectable”. The usual value of 5 sigma (based on a standard normal distribution) corresponds to a 1 in 3.5 million chance of a false positive.

  • log_transform (bool) – Whether to apply a log transformation to the FPF before interpolating it to determine the detection limit (i.e., work with logFPF).

  • aggregation_function (Callable[[ndarray], float]) – The function that is used to aggregate the results for the six azimuthal positions into a single value. Must take a 1D numpy array as an input and return a float. Usually, either the mean or the median is used. Using the min / max can give an estimate for the worst / best case.

Returns:

A 2-tuple, (separations, detection_limits), which contains the separations and the corresponding detection limit.

Return type:

Tuple[ndarray, ndarray]