vip_hci.metrics package

Submodules

vip_hci.metrics.completeness module

Module with completeness curve and map generation function.

[DAH21b] (1,2,3,4)

Dahlqvist et al. 2021b

Auto-RSM: An automated parameter-selection algorithm for the RSM map exoplanet detection algorithm

Astronomy & Astrophysics, Volume 656, Issue 2, p. 54

https://arxiv.org/abs/2109.14318

[JEN18] (1,2)

Jensen-Clem et al. 2018

A New Standard for Assessing the Performance of High Contrast Imaging Systems

The Astrophysical Journal, Volume 155, Issue 1, p. 19

https://arxiv.org/abs/1711.01215

[MAW14] (1,2,3,4,5,6,7,8)

Mawet et al. 2014

Fundamental Limitations of High Contrast Imaging Set by Small Sample Statistics

The Astrophysical Journal, Volume 792, Issue 1, p. 97

https://arxiv.org/abs/1407.2247

vip_hci.metrics.completeness.completeness_curve(cube, angle_list, psf, fwhm, algo, an_dist=None, ini_contrast=None, starphot=1, pxscale=0.1, n_fc=20, completeness=0.95, snr_approximation=True, max_iter=50, nproc=1, algo_dict={}, verbose=True, plot=True, dpi=100, save_plot=None, object_name=None, fix_y_lim=(), figsize=(8, 5), algo_class=None)

Function allowing the computation of completeness-based contrast curves with any of the psf-subtraction algorithms provided by VIP. The code relies on the approach proposed in [DAH21b], itself inspired by the framework developed in [JEN18]. It relies on the computation of the contrast associated to a completeness level achieved at a level defined as the first false positive in the original SNR map (brightest speckle observed in the empty map) instead of the computation o the local noise and throughput (see the vip_hci.metrics.contrast_curve function). The computation of the completeness level associated to a contrast is done via the sequential injection of multiple fake companions. The algorithm uses multiple interpolations to find the contrast associated to the selected completeness level (0.95 by default). More information about the algorithm can be found in [DAH21b].

Parameters:

• cube (3d or 4d numpy ndarray) – The input cube, 3d (ADI data) or 4d array (IFS data), without fake companions.

• angle_list (1d numpy ndarray) – Vector with parallactic angles.

• psf (2d or 3d numpy ndarray) – Frame with the psf template for the fake companion(s). PSF must be centered in array. Normalization is done internally.

• fwhm (int or float or 1d array, optional) – The the Full Width Half Maximum in pixels. It can handle a different FWHM value for different wavelengths (IFS data).

• algo (callable or function) – The post-processing algorithm, e.g. vip_hci.pca.pca.

• an_dist (list or ndarray, optional) – List of angular separations for which a contrast has to be estimated. Default is None which corresponds to a range spanning 2 FWHM to half the size of the provided cube - PSF size //2 with a step of 5 pixels

• ini_contrast (list, 1d ndarray or None, optional) – Initial contrast for the range of angular separations included in an_dist. The number of initial contrasts should be equivalent to the number of angular separations. Default is None which corresponds to the 5-sigma contrast_curve obtained with vip_hci.metrics.contrast_curve.

• starphot (int or float or 1d array, optional) – If int or float it corresponds to the aperture photometry of the non-coronagraphic PSF which we use to scale the contrast. Default is 1, which corresponds to an output contrast expressed in ADU.

• pxscale (float, optional) – Plate scale or pixel scale of the instrument. Only used for plots.

• n_fc (int, optional) – Number of azimuths considered for the computation of the True positive rate/completeness,(number of fake companions injected sequentially). The number of azimuths is defined such that the selected completeness is reachable (e.g. 95% of completeness requires at least 20 fake companion injections). Default 20.

• completeness (float, optional) – The completeness level to be achieved when computing the contrasts, i.e. the True positive rate reached at the threshold associated to the first false positive (the first false positive is defined as the brightest speckle present in the entire detection map). Default 95.

• snr_approximation (bool, optional) – If True, an approximated S/N map is generated. If False the approach of [MAW14] is used. Default is True, for speed.

• max_iter (int, optional) – Maximum number of iterations to consider in the search for the contrast level achieving desired completeness before considering it unachievable.

• nproc (int or None, optional) – Number of processes for parallel computing.

• algo_dict (dictionary, optional) – Any other valid parameter of the post-processing algorithms can be passed here, including e.g. imlib and interpolation.

• verbose (bool, optional) – Whether to print more info while running the algorithm. Default: True.

• plot (bool, optional) – Whether to plot the final contrast curve or not. True by default.

• dpi (int optional) – Dots per inch for the plots. 100 by default. 300 for printing quality.

• save_plot (string or None, optional) – If provided, the contrast curve will be saved to this path.

• object_name (string or None, optional) – Target name, used in the plot title.

• fix_y_lim (tuple, optional) – If provided, the y axis limits will be fixed, for easier comparison between plots.

• fig_size (tuple, optional) – Figure size

Returns:

• an_dist (1d numpy ndarray) – Radial distances where the contrasts are calculated

• cont_curve (1d numpy ndarray) – Contrasts for the considered radial distances and selected completeness level.

vip_hci.metrics.completeness.completeness_map(cube, angle_list, psf, fwhm, algo, an_dist, ini_contrast, starphot=1, n_fc=20, snr_approximation=True, nproc=1, algo_dict={}, verbose=True, algo_class=None)

Function allowing the computation of two dimensional (radius and completeness) contrast curves with any psf-subtraction algorithm provided by VIP. The code relies on the approach proposed by [DAH21b], itself inspired by the framework developped in [JEN18]. It relies on the computation of the contrast associated to a completeness level achieved at a level defined as the first false positive in the original SNR map (brightest speckle observed in the empty map). The computation of the completeness level associated to a contrast is done via the sequential injection of multiple fake companions. The algorithm uses multiple interpolations to find the contrast associated to the selected completeness level (0.95 by default). The function allows the computation of three dimensional completeness maps, with contrasts computed for multiple completeness level, allowing the reconstruction of the contrast/completeness distribution for every considered angular separations. For more details see [DAH21b].

Parameters:

• cube (3d or 4d numpy ndarray) – The input cube, 3d (ADI data) or 4d array (IFS data), without fake companions.

• angle_list (1d numpy ndarray) – Vector with parallactic angles.

• psf (2d or 3d numpy ndarray) – Frame with the psf template for the fake companion(s). PSF must be centered in array. Normalization is done internally.

• fwhm (int or float or 1d array, optional) – The the Full Width Half Maximum in pixels. It can handle a different FWHM value for different wavelengths (IFS data).

• algo (callable or function) – The post-processing algorithm, e.g. vip_hci.pca.pca.

• an_dist (list or ndarray) – List of angular separations for which a contrast has to be estimated. Default is None which corresponds to a range of spanning between 2 FWHM and half the size of the provided cube - PSF size //2 with a step of 5 pixels

• ini_contrast (list, 1d ndarray or None, optional) – Initial contrast for the range of angular separations included in an_dist. The number of initial contrasts should be equivalent to the number of angular separations. Default is None which corresponds to the 5-sigma contrast_curve obtained with vip_hci.metrics.contrast_curve.

• starphot (int or float or 1d array) – If int or float it corresponds to the aperture photometry of the non-coronagraphic PSF which we use to scale the contrast. Default is 1 which corresponds to the contrast expressed in ADU.

• n_fc (int, optional) – Number of azimuths considered for the computation of the True positive rate/completeness, (number of fake companions injected separately). The range of achievable completeness depends on the number of considered azimuths (the minimum completeness is defined as 1/n_fc and the maximum is 1-1/n_fc). Default is 20.

• snr_approximated (bool, optional) – If True, an approximated S/N map is generated. If False the approach of [MAW14] is used. Default is True

• nproc (int or None) – Number of processes for parallel computing.

• algo_dict – Any other valid parameter of the post-processing algorithms can be passed here, including e.g. imlib and interpolation.

• verbose (Boolean, optional) – If True the function prints intermediate info about the comptation of the completeness map. Default is True.

Returns:

• an_dist (1d numpy ndarray) – Radial distances where the contrasts are calculated

• comp_levels (1d numpy ndarray) – Completeness levels for which the contrasts are calculated

• cont_curve (2d numpy ndarray) – Contrast matrix, with the first axis associated to the radial distances and the second axis associated to the completeness level, calculated from 1/n_fc to (n_fc-1)/n_fc.

vip_hci.metrics.contrcurve module

Module with contrast curve generation function.

vip_hci.metrics.contrcurve.aperture_flux(array, yc, xc, fwhm, ap_factor=1, mean=False, verbose=False)

Return the sum of pixel values in a circular aperture centered on the input coordinates. The radius of the aperture is set as (ap_factor*fwhm)/2.

Parameters:

• array (numpy ndarray) – Input frame.

• yc (list or 1d arrays) – List of y and x coordinates of sources.

• xc (list or 1d arrays) – List of y and x coordinates of sources.

• fwhm (float) – FWHM in pixels.

• ap_factor (int, optional) – Diameter of aperture in terms of the FWHM.

Returns:

flux – List of fluxes.

Return type:

list of floats

Note

From Photutils documentation, the aperture photometry defines the aperture using one of 3 methods:

‘center’: A pixel is considered to be entirely in or out of the aperture

depending on whether its center is in or out of the aperture.

‘subpixel’: A pixel is divided into subpixels and the center of each

subpixel is tested (as above).

‘exact’: (default) The exact overlap between the aperture and each pixel is

calculated.

vip_hci.metrics.contrcurve.contrast_curve(cube, angle_list, psf_template, fwhm, pxscale, starphot, algo, sigma=5, nbranch=1, theta=0, inner_rad=1, fc_rad_sep=3, noise_sep=1, wedge=(0, 360), fc_snr=100, student=True, transmission=None, smooth=True, interp_order=2, plot=True, dpi=100, debug=False, verbose=True, full_output=False, save_plot=None, object_name=None, frame_size=None, fix_y_lim=(), figsize=(8, 5), algo_class=None, **algo_dict)

Computes the contrast curve at a given confidence (sigma) level for an ADI cube or ADI+IFS cube. The contrast is calculated as sigma*noise/throughput. This implementation takes into account the small sample statistics correction proposed in [MAW14].

Parameters:

• cube (3d or 4d numpy ndarray) – The input cube, 3d (ADI data) or 4d array (IFS data), without fake companions.

• angle_list (1d numpy ndarray) – Vector with parallactic angles.

• psf_template (2d or 3d numpy ndarray) – Frame with the psf template for the fake companion(s). PSF must be centered in array. Normalization is done internally.

• fwhm (int or float or 1d array, optional) – The the Full Width Half Maximum in pixels. It can handle a different FWHM value for different wavelengths (IFS data).

• pxscale (float) – Plate scale or pixel scale of the instrument (only used for plots)

• starphot (int or float or 1d array) – If int or float it corresponds to the aperture photometry of the non-coronagraphic PSF which we use to scale the contrast. If a vector is given it must contain the photometry correction for each frame.

• algo (callable or function) – The post-processing algorithm, e.g. vip_hci.pca.pca.

• sigma (int) – Sigma level for contrast calculation. Note this is a “Gaussian sigma” regardless of whether Student t correction is performed (set by the ‘student’ parameter). E.g. setting sigma to 5 will yield the contrast curve corresponding to a false alarm probability of 3e-7.

• nbranch (int, optional) – Number of branches on which to inject fakes companions. Each branch is tested individually.

• theta (float, optional) – Angle in degrees for rotating the position of the first branch that by default is located at zero degrees. Theta counts counterclockwise from the positive x axis. When working on a wedge, make sure that theta is located inside of it.

• inner_rad (int, optional) – Innermost radial distance to be considered in terms of FWHM. Should be >= 1.

• fc_rad_sep (int optional) – Radial separation between the injected companions (in each of the patterns) in FWHM. Must be large enough to avoid overlapping. With the maximum possible value, a single fake companion will be injected per cube and algorithm post-processing (which greatly affects computation time).

• noise_sep (int or None, optional) – Radial sampling of the noise level. By default it is performed with a radial step of 1 pixel. If set to None, it will be automatically set to be sampled every fwhm pixels radially.

• wedge (tuple of floats, optional) – Initial and Final angles for using a wedge. For example (-90,90) only considers the right side of an image.

• fc_snr (float optional) – Signal to noise ratio of injected fake companions (w.r.t a Gaussian distribution).

• student (bool, optional) – If True uses Student t correction to inject fake companion.

• transmission (numpy array, optional) – Radial transmission of the coronagraph, if any. Array with either 2 x n_rad or 1+n_ch x n_rad columns. The first column should contain the radial separation in pixels, while the other column(s) are the corresponding off-axis transmission (between 0 and 1), for either all, or each spectral channel (only relevant for a 4D input cube).

• smooth (bool, optional) – If True the radial noise curve is smoothed with a Savitzky-Golay filter of order 2.

• interp_order (int or None, optional) – If an integer is provided, the throughput vector is interpolated with a spline of order interp_order. Takes values from 1 to 5. If None, then the throughput is not interpolated.

• plot (bool, optional) – Whether to plot the final contrast curve or not. True by default.

• dpi (int optional) – Dots per inch for the plots. 100 by default. 300 for printing quality.

• imlib ({'opencv', 'ndimage-fourier', 'ndimage-interp', 'vip-fft'}, str opt) – Library or method used for image operations (rotations). Opencv is the default for being the fastest. See description of vip_hci.preproc.frame_rotate.

• interpolation (str, opt) – See description of vip_hci.preproc.frame_rotate function

• debug (bool, optional) – Whether to print and plot additional info such as the noise, throughput, the contrast curve with different X axis and the delta magnitude instead of contrast.

• verbose ({True, False, 0, 1, 2}, optional) – If True or 1 the function prints to stdout intermediate info and timing, if set to 2 more output will be shown.

• full_output (bool, optional) – If True returns intermediate arrays.

• save_plot (string or None, optional) – If provided, the contrast curve will be saved to this path.

• object_name (string or None, optional) – Target name, used in the plot title.

• frame_size (int, optional) – Frame size used for generating the contrast curve, used in the plot title.

• fix_y_lim (tuple, optional) – If provided, the y axis limits will be fixed, for easier comparison between plots.

• fig_size (tuple, optional) – Figure size

• **algo_dict – Any other valid parameter of the post-processing algorithms can be passed here, including e.g. imlib and interpolation.

Returns:

• datafr (pandas dataframe) – Dataframe containing the sensitivity (Gaussian and Student corrected if Student parameter is True), the interpolated throughput, the distance in pixels, the noise and the sigma corrected (if Student is True).

• If full_output is True then the function returns – datafr, cube_fc_all, frame_fc_all, frame_nofc and fc_map_all.

• frame_fc_all (numpy ndarray) – 3d array with the 3 frames of the 3 (patterns) processed cubes with companions.

• frame_nofc (numpy ndarray) – 2d array, PCA processed frame without companions.

• fc_map_all (numpy ndarray) – 3d array with 3 frames containing the position of the companions in the 3 patterns.

vip_hci.metrics.contrcurve.noise_per_annulus(array, separation, fwhm, init_rad=None, wedge=(0, 360), verbose=False, debug=False)

Measure the noise and mean residual level as the standard deviation and mean, respectively, of apertures defined in each annulus with a given separation.

The annuli start at init_rad (= fwhm by default if not provided) and stop 2*separation before the edge of the frame.

Parameters:

• array (numpy ndarray) – Input frame.

• separation (float) – Separation in pixels of the centers of the annuli measured from the center of the frame.

• fwhm (float) – FWHM in pixels.

• init_rad (float) – Initial radial distance to be used. If None then the init_rad = FWHM.

• wedge (tuple of floats, optional) – Initial and Final angles for using a wedge. For example (-90,90) only considers the right side of an image. Be careful when using small wedges, this leads to computing a standard deviation of very small samples (<10 values).

• verbose (bool, optional) – If True prints information.

• debug (bool, optional) – If True plots the positioning of the apertures.

Returns:

• noise (numpy ndarray) – Vector with the noise value per annulus.

• res_level (numpy ndarray) – Vector with the mean residual level per annulus.

• vector_radd (numpy ndarray) – Vector with the radial distances values.

vip_hci.metrics.contrcurve.throughput(cube, angle_list, psf_template, fwhm, algo, nbranch=1, theta=0, inner_rad=1, fc_rad_sep=3, wedge=(0, 360), fc_snr=100, noise_sep=1, full_output=False, verbose=True, algo_class=None, **algo_dict)

Measure the throughput for chosen algorithm and input dataset (ADI or ADI+mSDI).

The final throughput is the average of the same procedure measured in nbranch azimutally equidistant branches.

Parameters:

• cube (3d or 4d numpy ndarray) – The input cube, 3d (ADI data) or 4d array (IFS data), without fake companions.

• angle_list (1d numpy ndarray) – Vector with parallactic angles.

• psf_template (2d or 3d numpy ndarray) – Frame with the psf template for the fake companion(s). PSF must be centered in array. Normalization is done internally.

• fwhm (int or float or 1d array, optional) – The the Full Width Half Maximum in pixels. It can handle a different FWHM value for different wavelengths (IFS data).

• algo (callable or function) – The post-processing algorithm, e.g. vip_hci.pca.pca. Third party Python algorithms can be plugged here. They must have the parameters: ‘cube’, ‘angle_list’ and ‘verbose’. Optionally a wrapper function can be used.

• nbranch (int optional) – Number of branches on which to inject fakes companions. Each branch is tested individually.

• theta (float, optional) – Angle in degrees for rotating the position of the first branch that by default is located at zero degrees. Theta counts counterclockwise from the positive x axis.

• inner_rad (int, optional) – Innermost radial distance to be considered in terms of FWHM. Should be >= 1.

• fc_rad_sep (int optional) – Radial separation between the injected companions (in each of the patterns) in FWHM. Must be large enough to avoid overlapping. With the maximum possible value, a single fake companion will be injected per cube and algorithm post-processing (which greatly affects computation time).

• wedge (tuple of floats, optional) – Initial and Final angles for using a wedge. For example (-90,90) only considers the right side of an image.

• fc_snr (float optional) – Signal to noise ratio of injected fake companions (w.r.t a Gaussian distribution).

• noise_sep (int or None, optional) – Radial sampling of the noise level. By default it is performed with a radial step of 1 pixel. If set to None, it will be automatically set to be sampled every fwhm pixels radially.

• full_output (bool, optional) – If True returns intermediate arrays.

• verbose (bool, optional) – If True prints out timing and information.

• **algo_dict – Parameters of the post-processing algorithms can be passed here, including e.g. imlib, interpolation or nproc.

Returns:

• thruput_arr (numpy ndarray) – 2d array whose rows are the annulus-wise throughput values for each branch.

• vector_radd (numpy ndarray) – 1d array with the distances in FWHM (the positions of the annuli).

• If full_output is True then the function returns (thruput_arr, noise,)

• vector_radd, cube_fc_all, frame_fc_all, frame_nofc and fc_map_all.

• noise (numpy ndarray) – 1d array with the noise per annulus.

• frame_fc_all (numpy ndarray) – 3d array with the 3 frames of the 3 (patterns) processed cubes with companions.

• frame_nofc (numpy ndarray) – 2d array, PCA processed frame without companions.

• fc_map_all (numpy ndarray) – 3d array with 3 frames containing the position of the companions in the 3 patterns.

vip_hci.metrics.detection module

Module with detection algorithms.

vip_hci.metrics.detection.detection(array, fwhm=4, psf=None, mode='lpeaks', bkg_sigma=5, matched_filter=False, mask=True, snr_thresh=5, nproc=1, plot=True, debug=False, full_output=False, verbose=True, **kwargs)

Automatically find point-like sources in a 2d array.

The algorithm is designed for automatically finding planets in post-processed high contrast final frames. Blob can be defined as a region of an image in which some properties are constant or vary within a prescribed range of values. See Notes below to read about the algorithm details.

Parameters:

• array (numpy ndarray, 2d) – Input frame.

• fwhm (None or int, optional) – Size of the FWHM in pixels. If None and a psf is provided, then the FWHM is measured on the PSF image.

• psf (numpy ndarray) – Input PSF template. It must be normalized with the vip_hci.metrics.normalize_psf function.

• mode ({'lpeaks', 'log', 'dog', 'snrmap', 'snrmapf'}, optional) – Sets with algorithm to use. Each algorithm yields different results. See notes for the details of each method.

• bkg_sigma (int or float, optional) – The number standard deviations above the clipped median for setting the background level. Used when mode is either ‘lpeaks’, ‘dog’ or ‘log’.

• matched_filter (bool, optional) – Whether to correlate with the psf of not. Used when mode is either ‘lpeaks’, ‘dog’ or ‘log’.

• mask (bool, optional) – If True the central region (circular aperture of 2*FWHM radius) of the image will be masked out.

• snr_thresh (float, optional) – S/N threshold for deciding whether the blob is a detection or not. Used to threshold the S/N map when mode is set to ‘snrmap’ or ‘snrmapf’.

• nproc (None or int, optional) – The number of processes for running the snrmap function.

• plot (bool, optional) – If True plots the frame showing the detected blobs on top.

• debug (bool, optional) – Whether to print and plot additional/intermediate results.

• full_output (bool, optional) – Whether to output just the coordinates of blobs that fulfill the SNR constraint or a table with all the blobs and the peak pixels and SNR.

• verbose (bool, optional) – Whether to print to stdout information about found blobs.

• **kwargs (dictionary, optional) – Arguments to be passed to plot_frames to customize the plot (and to save it to disk).

Returns:

• yy, xx (numpy ndarray) – Two vectors with the y and x coordinates of the centers of the sources (potential planets).

• If full_output is True then a table with all the candidates that passed the

• 2d Gaussian fit constrains and the S/N threshold is returned.

Note

When mode is either ‘lpeaks’, ‘dog’ or ‘log’, the detection might happen in the input frame or in a match-filtered version of it (by setting matched_filter to True and providing a PSF template, to run a correlation filter). Filtering the image will smooth the noise and maximize detectability of objects with a shape similar to the kernel. When mode is either ‘snrmap’ or ‘snrmapf’, the detection is done on an S/N map directly.

When mode is set to:

‘lpeaks’ (Local maxima): The local peaks above the background (computed

using sigma clipped statistics) on the (correlated) frame are detected. A maximum filter is used for finding local maxima. This operation dilates the original image and merges neighboring local maxima closer than the size of the dilation. Locations where the original image is equal to the dilated image are returned as local maxima. The minimum separation between the peaks is 1*FWHM.

‘log’ (Laplacian of Gaussian): It computes the Laplacian of Gaussian

images with successively increasing standard deviation and stacks them up in a cube. Blobs are local maximas in this cube. LOG assumes that the blobs are again assumed to be bright on dark.

‘dog’ (Difference of Gaussians): This is a faster approximation of the

Laplacian of Gaussian approach. In this case the image is blurred with increasing standard deviations and the difference between two successively blurred images are stacked up in a cube. DOG assumes that the blobs are again assumed to be bright on dark.

‘snrmap’ or ‘snrmapf’: A threshold is applied to the S/N map, computed

with the snrmap function (snrmapf calls snrmap with approximated set to True). The threshold is given by snr_thresh and local maxima are found as in the case of ‘lpeaks’.

Finally, a 2d Gaussian fit is done on each of the potential blobs constraining the position on a cropped sub-image and the sigma of the fit (to match the input FWHM). Finally the blobs are filtered based on its S/N value, according to snr_thresh.

vip_hci.metrics.detection.mask_source_centers(array, fwhm, y=None, x=None)

Creates a mask of ones with the size of the input frame and zeros at the center of the sources (planets) with coordinates x, y. If y and x are not provided, the sources will be found automatically using ‘detection()’ (‘log’ mode).

Parameters:

• array (numpy ndarray) – Input frame.

• fwhm (float) – Size in pixels of the FWHM.

• y (tuples of int (optional)) – Coordinates of the center of the sources.

• x (tuples of int (optional)) – Coordinates of the center of the sources.

Returns:

mask – Mask frame.

Return type:

numpy ndarray

vip_hci.metrics.detection.mask_sources(mask, ap_rad)

Given an input mask with zeros only at the center of source locations (ones elsewhere), returns a mask with zeros within a radius ap_rad of all sources.

Parameters:

• mask (numpy ndarray) – Input mask with zeros at sources center. Mask has to be square.

• ap_rad (float) – Size in pixels of the apertures that should be filled with zeros around each source in the mask.

Returns:

mask_out – Output mask frame.

Return type:

numpy ndarray

vip_hci.metrics.detection.peak_coordinates(obj_tmp, fwhm, approx_peak=None, search_box=None, channels_peak=False)

Find the pixel coordinates of maximum in either a frame or a cube, after convolution with gaussian. It first applies a gaussian filter, to lower the probability of returning a hot pixel (although it may still happen with clumps of hot pixels, hence parameter “approx_peak”).

Parameters:

• obj_tmp (cube_like or frame_like) – Input 3d cube or image.

• fwhm (float_like or 1d array) – Input full width half maximum value of the PSF in pixels. This will be used as the standard deviation for Gaussian kernel of the Gaussian filtering. Can be a 1d array if obj_tmp is a 3D cube.

• approx_peak (2 components list or array, opt) – Gives the approximate yx coordinates of the peak.

• search_box (float or 2 components list or array, opt) – Gives the half-size in pixels of a box in which the peak is searched, around approx_peak. If float, it is assumed the same box size is wanted in both y and x. Note that this parameter should be provided if approx_peak is provided.

• channels_peak (bool, {False, True}, opt) – Whether returns the indices of the peak in each channel in addition to the global indices of the peak in the cube. If True, it would hence return two 1d-arrays. (note: only available if the input is a 3d cube)

Returns:

• (zz_max,) yy_max, xx_max (integers) – Indices of peak in either 3D or 2D array

• ind_ch_max (2d array) – Coordinates of the peak in each channel

vip_hci.metrics.roc module

ROC curves generation.

class vip_hci.metrics.roc.EvalRoc(dataset, plsc=0.0272, n_injections=100, inrad=8, outrad=12, dist_flux=('uniform', 2, 500), mask=None)

Bases: object

Class for the generation of receiver operating characteristic (ROC) curves.

add_algo(name, algo, color, symbol, thresholds)

Parameters:

• algo (HciPostProcAlgo)

• thresholds (list of lists)

compute_tpr_fps(**kwargs)

Calculate number of dets/fps for every injection/method/threshold.

Take the probability maps and the desired thresholds for every method, and calculates the binary map, number of detections and FPS using compute_binary_map. Sets each methods detections, fps and bmaps attributes.

Parameters:

**kwargs (keyword arguments) – Passed to compute_binary_map

inject_and_postprocess(patch_size, cevr=0.9, expvar_mode='annular', nproc=1)

plot_detmaps(i=None, thr=9, dpi=100, axis=True, grid=False, vmin=-10, vmax='max', plot_type='horiz')

Plot the detection maps for one injection.

Parameters:

• i (int or None, optional) – Index of the injection, between 0 and self.n_injections. If None, takes the 30st injection, or if there are less injections, the middle one.

• thr (int, optional) – Index of the threshold.

• dpi – Passed to pp_subplots

• axis – Passed to pp_subplots

• grid – Passed to pp_subplots

• vmin – Passed to pp_subplots

• vmax – Passed to pp_subplots

• plot_type ({"horiz" or "vert"}, optional) –

  Plot type.

  horiz

  One row per algorithm (frame, probmap, binmap)

  vert

  1 row for final frames, 1 row for probmaps and 1 row for binmaps

plot_roc_curves(dpi=100, figsize=(5, 5), xmin=None, xmax=None, ymin=-0.05, ymax=1.02, xlog=True, label_skip_one=False, legend_loc='lower right', legend_size=6, show_data_labels=True, hide_overlap_label=True, label_gap=(0, -0.028), save_plot=False, label_params={}, line_params={}, marker_params={}, verbose=True)

vip_hci.metrics.roc.compute_binary_map(frame, thresholds, injections, fwhm, npix=1, overlap_threshold=0.7, max_blob_fact=2, plot=False, debug=False)

Take a list of thresholds, create binary maps and counts detections/fps. A blob which is “too big” is split into apertures, and every aperture adds one ‘false positive’.

Parameters:

• frame (numpy ndarray) – Detection map.

• thresholds (list or numpy ndarray) – List of thresholds (detection criteria).

• injections (tuple, list of tuples) – Coordinates (x,y) of the injected companions. Also accepts 1d/2d ndarrays.

• fwhm (float) – FWHM, used for obtaining the size of the circular aperture centered at the injection position (and measuring the overlapping with found blobs). The circular aperture has 2 * FWHM in diameter.

• npix (int, optional) – The number of connected pixels, each greater than the given threshold, that an object must have to be detected. npix must be a positive integer. Passed to detect_sources function from photutils.

• overlap_threshold (float) – Percentage of overlap a blob has to have with the aperture around an injection.

• max_blob_fact (float) – Maximum size of a blob (in multiples of the resolution element) before it is considered as “too big” (= non-detection).

• plot (bool, optional) – If True, a final resulting plot summarizing the results will be shown.

• debug (bool, optional) – For showing optional information.

Returns:

• list_detections (list of int) – List of detection count for each threshold.

• list_fps (list of int) – List of false positives count for each threshold.

• list_binmaps (list of 2d ndarray) – List of binary maps: detection maps thresholded for each threshold value.

vip_hci.metrics.snr_source module

Module with S/N calculation functions. We strongly recommend users to read [MAW14] before using routines of this module.

vip_hci.metrics.snr_source.frame_report(array, fwhm, source_xy=None, verbose=True, **snr_arguments)

Provide info about candidate companions in a given post-processed frame.

Either a list of source positions is passed, or the position with the highest is automatically considered. Integrated flux in aperture, S/N of central pixel (either source_xy or at max S/N value), mean S/N in aperture at those/that location.

Parameters:

• array (numpy ndarray) – 2d array or input frame.

• fwhm (float) – Size of the FWHM in pixels.

• source_xy (tuple of floats or list (of tuples of floats)) – X and Y coordinates of the center(s) of the source(s).

• verbose (bool, optional) – If True prints to stdout the frame info.

• snr_arguments (dictionary, optional) – Optional parameters for the vip_hci.metrics.snrmap function.

Returns:

• source_xy (tuple of floats or list (of tuples of floats)) – X and Y coordinates of the center(s) of the source(s).

• obj_flux (list of floats) – Integrated flux in aperture.

• snr_centpx (list of floats) – S/N of the source_xy pixels.

• meansnr_pixels (list of floats) – Mean S/N of pixels in 1xFWHM apertures centered on source_xy.

vip_hci.metrics.snr_source.indep_ap_centers(array, source_xy, fwhm, exclude_negative_lobes=False, exclude_theta_range=None, no_gap=False)

Define independent aperture centers at a given radial separation, starting from a test location provided with source_xy.

Parameters:

• array (numpy ndarray, 2d) – Frame in which the apertures will be defined (its dimensions are used).

• source_xy (tuple of floats) – X and Y coordinates of the planet or test speckle.

• fwhm (float) – Size in pixels of the FWHM, corresponding to the diameter of the non-overlapping apertures.

• exclude_negative_lobes (bool, opt) – Whether to include the adjacent aperture lobes to the tested location or not. Can be set to True if the image shows significant neg lobes.

• exclude_theta_range (tuple of 2 floats or None, opt) – If provided, range of trigonometric angles in deg (measured from positive x axis), to be avoided for apertures used for noise estimation. WARNING: this is to be used wisely, e.g. only if a known authentic circumstellar signal is biasing the SNR estimate.

• no_gap (bool, opt) – Whether an overlapping aperture is defined between the first and last non-overlapping aperture (at the end of making a full circle), in order to leave no gap. False by default.

Returns:

(yy, xx) – Tuple containing y and x coordinates of the apertures

Return type:

tuple of 2 numpy ndarray

vip_hci.metrics.snr_source.significance(snr, rad, fwhm, student_to_gauss=True, verbose=True)

Convert a S/N ratio (measured as in [MAW14]) into a Gaussian significance (n-sigma) with equivalent false alarm probability for a point-source detection measured at a given separation, or the opposite.

Parameters:

• snr (float or numpy array) – SNR value(s)

• rad (float or numpy array) – Radial separation(s) from the star in pixels. If an array, it should be the same shape as snr and provide the radial separation corresponding to each snr measurement.

• fwhm (float) – Full Width Half Maximum of the PSF.

• student_to_gauss (bool, optional) – Whether the conversion is from Student SNR to Gaussian significance (True), or the opposite (False).

Returns:

sig – Equivalent Gaussian significance [student_to_gauss=True] or equivalent Student S/N ratio [student_to_gauss=False].

Return type:

float

vip_hci.metrics.snr_source.snr(array, source_xy, fwhm, full_output=False, array2=None, use2alone=False, exclude_negative_lobes=False, exclude_theta_range=None, plot=False, verbose=False)

Calculate the S/N (signal to noise ratio) of a test resolution element in a residual frame (e.g. post-processed with LOCI, PCA, etc). Implements the approach described in [MAW14] on small sample statistics, where a student t-test (eq. 9) can be used to determine S/N (and contrast) in high contrast imaging. 3 extra possibilities compared to [MAW14]:

• possibility to provide a second array (e.g. obtained with opposite derotation angles) to have more apertures for noise estimation;

• possibility to exclude negative ADI lobes directly adjacent to the tested xy location, to not bias the noise estimate;

• possibility to use only the second array for the noise estimation (useful for images containing a lot of disk/extended signals).

* DISCLAIMER * Signal-to-noise ratio is not significance! For a conversion from snr to n-sigma (i.e. the equivalent confidence level of a Gaussian n-sigma), use the significance() function.

Parameters:

• array (numpy ndarray, 2d) – Post-processed frame where we want to measure S/N.

• source_xy (tuple of floats) – X and Y coordinates of the planet or test speckle.

• fwhm (float) – Size in pixels of the FWHM.

• full_output (bool, optional) – If True returns back the S/N value, the y, x input coordinates, noise and flux.

• array2 (None or numpy ndarray, 2d, optional) – Additional image (e.g. processed image with negative derotation angles) enabling to have more apertures for noise estimation at each radial separation. Should have the same dimensions as array.

• use2alone (bool, opt) – Whether to use array2 alone to estimate the noise (can be useful to estimate the S/N of extended disk features)

• exclude_negative_lobes (bool, opt) – Whether to include the adjacent aperture lobes to the tested location or not. Can be set to True if the image shows significant neg lobes.

• exclude_theta_range (tuple of 2 floats or None, opt) – If provided, range of trigonometric angles in deg (measured from positive x axis), to be avoided for apertures used for noise estimation. WARNING: this is to be used wisely, e.g. only if a known authentic circumstellar signal is biasing the SNR estimate.

• plot (bool, optional) – Plots the frame and the apertures considered for clarity.

• verbose (bool, optional) – Chooses whether to print some output or not.

Returns:

• [if full_output=True (])

• sourcey (numpy ndarray) – [full_output=True] Input coordinates (source_xy) in Y.

• sourcex (numpy ndarray) – [full_output=True] Input coordinates (source_xy) in X.

• f_source (float) – [full_output=True] Flux in test elemnt.

• fluxes (numpy ndarray) – [full_output=True] Background apertures fluxes.

• [always (])

• snr_vale (float) – Value of the S/N for the given test resolution element.

vip_hci.metrics.snr_source.snrmap(array, fwhm, approximated=False, plot=False, known_sources=None, nproc=None, array2=None, use2alone=False, exclude_negative_lobes=False, verbose=True, **kwargs)

Parallel implementation of the S/N map generation function. Applies the S/N function (small samples penalty) at each pixel.

The S/N is computed as in [MAW14] for each radial separation.

DISCLAIMER: Signal-to-noise ratio is not significance! For a conversion from SNR to n-sigma (i.e. the equivalent confidence level of a Gaussian n-sigma), use the significance function.

Parameters:

• array (numpy ndarray) – Input frame (2d array).

• fwhm (float) – Size in pixels of the FWHM.

• approximated (bool, optional) – If True, an approximated S/N map is generated.

• plot (bool, optional) – If True plots the S/N map. False by default.

• known_sources (None, tuple or tuple of tuples, optional) – To take into account existing sources. It should be a tuple of float/int or a tuple of tuples (of float/int) with the coordinate(s) of the known sources.

• nproc (int or None) – Number of processes for parallel computing.

• array2 (numpy ndarray, optional) – Additional image (e.g. processed image with negative derotation angles) enabling to have more noise samples. Should have the same dimensions as array.

• use2alone (bool, optional) – Whether to use array2 alone to estimate the noise (might be useful to estimate the snr of extended disk features).

• verbose (bool, optional) – Whether to print timing or not.

• **kwargs (dictionary, optional) – Arguments to be passed to plot_frames to customize the plot (and to save it to disk).

Returns:

snrmap – Frame with the same size as the input frame with each pixel.

Return type:

2d numpy ndarray

vip_hci.metrics.stim module

Implementation of the STIM map from [PAI19]

[PAI19] (1,2,3)

Pairet et al. 2019

**STIM map: detection map for exoplanets imaging beyond asymptotic Gaussian

residual speckle noise** | MNRAS, 487, 2262 | `http://doi.org/10.1093/mnras/stz1350

<http://doi.org/10.1093/mnras/stz1350>`_

vip_hci.metrics.stim.inverse_stim_map(cube, angle_list, **rot_options)

Compute the inverse STIM detection map as in [PAI19].

Parameters:

• cube (3d numpy ndarray) – Non de-rotated residuals from reduction algorithm, eg. residuals_cube output from vip_hci.psfsub.pca.

• angle_list (numpy ndarray, 1d) – Corresponding parallactic angle for each frame.

• rot_options (dictionary, optional) – Dictionary with optional keyword values for “nproc”, “imlib”, “interpolation, “border_mode”, “mask_val”, “edge_blend”, “interp_zeros”, “ker” (see documentation of vip_hci.preproc.frame_rotate)

Returns:

inv_stim_map – Inverse STIM detection map.

Return type:

2d ndarray

vip_hci.metrics.stim.normalized_stim_map(cube, angle_list, mask=None, **rot_options)

Compute the normalized STIM detection map as in [PAI19].

Parameters:

• cube (3d numpy ndarray) – Non de-rotated residuals from reduction algorithm, eg. residuals_cube output from vip_hci.psfsub.pca.

• angle_list (numpy ndarray, 1d) – Corresponding parallactic angle for each frame.

• mask (int, float, numpy ndarray 2d or None) – Mask informing where the maximum value in the inverse STIM map should be calculated. If an integer or float, a circular mask with that radius masking the central part of the image will be used. If a 2D array, it should be a binary mask (ones in the areas that can be used).

• rot_options (dictionary, optional) – Dictionary with optional keyword values for “nproc”, “imlib”, “interpolation, “border_mode”, “mask_val”, “edge_blend”, “interp_zeros”, “ker” (see documentation of vip_hci.preproc.frame_rotate)

Returns:

normalized STIM map – STIM detection map.

Return type:

2d ndarray

vip_hci.metrics.stim.stim_map(cube_der)

Compute the STIM detection map as in [PAI19].

Parameters:

cube_der (3d numpy ndarray) – Input de-rotated cube, e.g. residuals_cube_ output from vip_hci.psfsub.pca.

Returns:

detection_map – STIM detection map.

Return type:

2d ndarray

Module contents

Subpackage metrics includes:

• signal-to-noise (S/N) estimation,

• S/N map generation,

• STIM map generation,

• detection of point like sources (for pipelines),

• fake companions injection,

• fake disks generation and injection,

• algorithms throughput estimation,

• contrast curve generation,

• completeness curve and map generation,

• receiver operating characteristic (ROC) curves generation.