residuals#

Methods for dealing with residuals.

hsr4hci.residuals.assemble_residual_stack_from_hypotheses(hypotheses, selection_mask, residuals)[source]#

Assemble the residual stack based on the selection_mask and the given hypotheses: For each spatial pixel where the selection_mask is True, use the residual from the model given by the respective entry in hypotheses; for all other pixels, use the “default” residual.

Parameters:

  • hypotheses (ndarray) – A 2D numpy array of shape (x_size, y_size). Each position contains an integers which represents the signal time which appears to be the best hypothesis for this pixel (i.e., “if there ever is a planet in this pixel, it should be at this time”).

  • selection_mask (ndarray) – A 2D numpy array of shape (x_size, y_size) which contains a mask that determines for which pixels the default residual is used and for which pixel the residual based on signal fitting / masking is used.

  • residuals (Union[File, Dict[str, ndarray]]) – The dictionary, or an open HDF file, which contains the full results from training both the “default” (vanilla) and the models based on signal fitting / masking.

Returns:

A 3D numpy array (whose shape matches the stack) containing the “best” residuals based on the given the hypotheses.

Return type:

ndarray

hsr4hci.residuals.get_gradient_mask(grid_size, frame_size, zero_radius=4)[source]#

Compute a gradient mask to re-weight the match fraction radially.

Rationale: The number of “affected pixels” that we use to compute a match fraction scales linearly with the separation from the star. For pixels very close to the center, only very few pixels contribute while for pixels at large separations, the MF is computed as the average of many pixels. To reduce both the number of false positives at small separations and false negative at large separations, it is useful to apply a “gradient mask” to the match fraction to re-weigh the MF values based on the separation from the center.

Parameters:

  • grid_size (int) – Frame size of the polar representation.

  • frame_size (Tuple[int, int]) – Frame size of the Cartesian representation.

  • zero_radius (int) – Radius (in pixels) around the center where the mask is set to zero; typically 1 FWHM. Even if there is a planet this close to the star, we should not be able to detect it.

Returns:

A gradient mask that can be used to re-weigh the polar MF map.

Return type:

ndarray

hsr4hci.residuals.get_residual_selection_mask(match_fraction, parang, psf_template, grid_size=128)[source]#

Based on the match_fraction, determine the selection_mask, that is, the mask that decides for which pixels we use the default model and for which we use the model based on signal fitting or signal masking.

Ideally, it would be sufficient to simply threshold the match fraction to obtain the selection mask. In practice, however, this does not always work well. Therefore, this function uses the following, more complex heuristic:

  1. Convert the match fraction from Cartesian to polar coordinates \((\rho, \phi)\).

  2. In polar coordinates, the planet signal is translation invariant; and even more importantly, we know exactly how it should look like. We can, therefore, compute a cross- correlation with the expected signal.

  3. In the result of this template matching, we can find peaks, which correspond to the \((\rho, \phi)\) position of the planet signals in the match fraction.

  4. Based on these peaks, we explicitly construct the selection mask. These masks are more interpretable and will not contain any “random” pixels or shapes, unlike the masks that can be obtained using the simple thresholding approach.

To further improve the result, some additional tricks (e.g., re- weighting of match fraction using a radial gradient) are used which have proven useful in preliminary experiments.

Parameters:

  • match_fraction (ndarray) – 2D numpy array containing the match fraction.

  • parang (ndarray) – 1D numpy array containing the parallactic angles.

  • psf_template (ndarray) – 2D numpy array containing the PSF template.

  • grid_size (int) – The size (width and height) of the match fraction when projecting to polar coordinates. This value should usually be chosen to be larger than the size of the MF in Cartesian coordinates (i.e, the usual frame size). Larger values can give better results, but slow things down.

Returns:

A 5-tuple of numpy array, consisting of

  1. The final selection_mask, that is, a 2D numpy array containing a binary mask that can be used to select the pixels for which the residuals based on signal fitting or signal masking should be used.

  2. The polar projection, that is, a 2D numpy array of shape (grid_size, grid_size) containing the polar projection of the match fraction (mostly for debugging purposes).

  3. The output of the template matching (“heatmap”), which has the same shape as (2). This is the cross-correlation of the polar projection with the expected signal.

  4. The template / expected signal, that is, a 2D numpy array of shape (grid_size, grid_size) that contains the approximate expected planet signal that we would hope to find in the polar projections.

  5. The positions of the (centers) of the planet trace arcs, as found by the cross-correlation procedure, that is, a 2D numpy array of shape (N, 2) where N is the number of found planet traces. Each tuple consists of the separation and the polar angle (in radian).

Return type:

Tuple[ndarray, ndarray, ndarray, ndarray, ndarray]