vip_hci.invprob package

Submodules

vip_hci.invprob.andromeda module

Implementation of the ANDROMEDA algorithm from [MUG09] / [CAN15].

Based on ANDROMEDA v3.1 from 28/06/2018.

[MUG09](1, 2, 3)
Mugnier et al, 2009
Optimal method for exoplanet detection by angular differential imaging
J. Opt. Soc. Am. A, 26(6), 1326-1334
doi:10.1364/JOSAA.26.001326
[CAN15](1, 2, 3)
Cantalloube et al, 2015
Direct exoplanet detection and characterization using the ANDROMEDA method: Performance on VLT/NaCo data
A&A, Volume 582, p. 89
https://arxiv.org/abs/1508.06406
vip_hci.invprob.andromeda.andromeda(cube, oversampling_fact, angles, psf, filtering_fraction=0.25, min_sep=0.5, annuli_width=1.0, roa=2, opt_method='lsq', nsmooth_snr=18, iwa=None, owa=None, precision=50, fast=False, homogeneous_variance=True, ditimg=1.0, ditpsf=None, tnd=1.0, total=False, multiply_gamma=True, nproc=1, verbose=False)[source]

Exoplanet detection in ADI sequences by maximum-likelihood approach, as implemented in [CAN15], itself inspired by the framework presented in [MUG09].

Parameters:
  • cube (3d numpy ndarray) – Input cube. IDL parameter: IMAGES_1_INPUT
  • oversampling_fact (float) – Oversampling factor for the wavelength corresponding to the filter used to obtain cube (defined as the ratio between the wavelength of the filter and the Shannon wavelength). Usually above 1 and below 3. Note that in ANDROMEDA everything is coded in lambda/D unit so this is an important parameter. See Note for example calculation. IDL parameter: OVERSAMPLING_1_INPUT
  • angles (numpy ndarray) – List of parallactic angles associated with each frame in cube. Note that, compared to the IDL version, the PA convention is different: If you would pass [1,2,3] to the IDL version, you should pass [-1, -2, -3] to this function to obtain the same results. IDL parameter: - ANGLES_INPUT
  • psf (2d numpy ndarray) – The experimental PSF used to model the planet signature in the subtracted images. This PSF is usually a non-coronographic or saturated observation of the target star. IDL parameter: PSF_PLANET_INPUT
  • filtering_fraction (float, optional) – Strength of the high-pass filter. If set to 1, no high-pass filter is used. IDL parameter: FILTERING_FRACTION_INPUT
  • min_sep (float, optional) – Angular separation is assured to be above min_sep*lambda/D. IDL parameter: MINIMUM_SEPARATION_INPUT
  • annuli_width (float, optional) – Annuli width on which the subtraction are performed. The same for all annuli. IDL parameter: ANNULI_WIDTH_INPUT
  • roa (float, optional) – Ratio of the optimization area. The optimization annulus area is defined by roa * annuli_width. roa is forced to 1 when opt_method="no" is chosen. IDL parameter: RATIO_OPT_AREA_INPUT
  • opt_method ({'no', 'total', 'lsq', 'robust'}, optional) – Method used to balance for the flux difference that exists between the two subtracted annuli in an optimal way during ADI. IDL parameter: OPT_METHOD_ANG_INPUT
  • nsmooth_snr (int, optional) – Number of pixels over which the radial robust standard deviation profile of the SNR map is smoothed to provide a global trend for the SNR map normalization. For nsmooth_snr=0 the SNR map normalization is disabled. IDL parameter: NSMOOTH_SNR_INPUT
  • iwa (float or None, optional) – Inner working angle / inner radius of the first annulus taken into account, expressed in lambda/D. If None, it is chosen automatically between the values 0.5, 4 or 0.25. IDL parameter: IWA_INPUT
  • owa (float, optional) – Outer working angle / inner radius of the last annulus, expressed in lambda/D. If None, the value is automatically chosen based on the frame size. IDL parameter: OWA_INPUT
  • precision (int, optional) – Number of shifts applied to the PSF. Passed to calc_psf_shift_subpix , which then creates a 4D cube with shape (precision+1, precision+1, N, N). IDL parameter: PRECISION_INPUT
  • fast (float or bool, optional) – Size of the annuli from which the speckle noise should not be dominant anymore, in multiples of lambda/D. If True, a value of 20 lambda/D is used, False (the default) disables the fast mode entirely. Above this threshold, the annuli width is set to 4*annuli_width. IDL parameter: FAST
  • homogeneous_variance (bool, optional) – If set, variance is treated as homogeneous and is calculated as a mean of variance in each position through time. IDL parameter: HOMOGENEOUS_VARIANCE_INPUT
  • ditimg (float, optional) – DIT for images (in sec) IDL Parameter: DITIMG_INPUT
  • ditpsf (float or None, optional) – DIT for PSF (in sec) IDL Parameter: DITPSF_INPUT If set to None, the value of ditimg is used.
  • tnd (float, optional) – Neutral Density Transmission. IDL parameter: TND_INPUT
  • total (bool, optional) – total=True is the old behaviour (normalizing the PSF to its sum). IDL parameter: TOTAL (was MAX in previous releases).
  • multiply_gamma (bool, optional) – Use gamma for signature computation too. IDL parameter: MULTIPLY_GAMMA_INPUT
  • nproc (int, optional) – Number of processes to use.
  • verbose (bool, optional) – Print some parameter values for control. IDL parameter: VERBOSE
Returns:

  • contrast (2d ndarray) – Calculated contrast map. (IDL return value)
  • snr (2d ndarray) – Signal to noise ratio map (defined as the estimated contrast divided by the estimated standard deviation of the contrast). IDL parameter: SNR_OUTPUT
  • snr_norm (2d ndarray) – IDL parameter: SNR_NORM_OUTPUT
  • stdcontrast (2d ndarray) – Map of the estimated standard deviation of the contrast. IDL parameter: STDDEVCONTRAST_OUTPUT` (previously STDEVFLUX_OUTPUT)
  • stdcontrast_norm (2d ndarray) – Map of the estimated normalized standard deviation of the contrast. IDL parameter: STDDEVCONTRAST_NORM_OUTPUT
  • likelihood (2d ndarray) – likelihood IDL parameter: LIKELIHOOD_OUTPUT
  • ext_radius (float) – Edge of the SNR map. Slightly decreased due to the normalization procedure. Useful to a posteriori reject potential companions that are too close to the edge to be analyzed. IDL parameter: EXT_RADIUS_OUTPUT

Notes

IDL outputs:

  • SNR_OUTPUT
  • SNR_NORM_OUTPUT
  • LIKELIHOOD_OUTPUT
  • STDDEVCONTRAST_OUTPUT (was STDEVFLUX_OUTPUT)
  • STDDEVCONTRAST_NORM_OUTPUT

The following IDL parameters were not implemented:

  • SDI-related parameters
    • IMAGES_2_INPUT
    • OVERSAMPLING_2_INPUT
    • OPT_METHOD_SPEC_INPUT
  • ROTOFF_INPUT
  • recentering (should be done in VIP before):
    • COORD_CENTRE_1_INPUT
    • COORD_CENTRE_2_INPUT
  • debug/expert testing testing
    • INDEX_NEG_INPUT
    • INDEX_POS_INPUT
    • ANNULI_LIMITS_INPUT
  • other
    • DISPLAY
    • VERSION
    • HELP
  • return parameters
    • IMAGES_1_CENTRED_OUTPUT
    • IMAGES_2_RESCALED_OUTPUT
    • VARIANCE_1_CENTRED_OUTPUT
    • VARIANCE_2_RESCALED_OUTPUT
    • GAMMA_INFO_OUTPUT
  • variances (VARIANCE_1_INPUT, VARIANCE_2_INPUT)

Note

The oversampling factor can be computed as: \(oversampling = plsc_{NYQ} / plsc\) , where: \(plsc = 12.25\) [mas/px] for SPHERE/IRDIS \(plsc_{NYQ} = (0.5*lambda/diam_tel)/pi*180*3600*1e3\) [mas/px] lambda = 3.8e-6 : Imaging wavelength [m] diam_tel = 8.0 : Telescope diameter [m]

vip_hci.invprob.fmmf module

Forward model matched filter relying on either KLIP [SOU12] / [PUE16] or LOCI [LAF07] for the PSF reference approximation. The original concept of matched filter applied to KLIP has been first proposed in [RUF17] and then adapted in [DAH21a] to use the LOCI framework. For both PSF-subtraction techniques, a forward model of the PSF is computed for each pixel contained in the field of view and each frame to account for the over-subtraction and self-subtraction of potential planetary signal due to the reference PSF subtraction. The obtained model is then compared to the pixels intensities within each frame of the residual cube. The SNR associated to each pixel contained in the field of view, as well as its estimated contrast is then obtained via a Gaussian maximum likelihood approach.

[DAH21a](1, 2, 3)
Dahlqvist et al. 2021a
Improving the RSM map exoplanet detection algorithm. PSF forward modelling and optimal selection of PSF subtraction techniques
The Astrophysical Journal Letters, Volume 646, p. 49
https://arxiv.org/abs/2012.05094
[LAF07]
Lafreniere et al. 2007
A New Algorithm for Point-Spread Function Subtraction in High-Contrast Imaging: A Demonstration with Angular Differential Imaging
The Astrophysical Journal, Volume 660, Issue 4, pp. 770-780
https://arxiv.org/abs/astro-ph/0702697
[PUE16]
Pueyo 2016
Detection and Characterization of Exoplanets using Projections on Karhunen Loeve Eigenimages: Forward Modeling
The Astrophysical Journal, Volume 824, Issue 2, p. 117
https://arxiv.org/abs/1604.06097
[RUF17](1, 2, 3)
Ruffio et al. 2017
Improving and Assessing Planet Sensitivity of the GPI Exoplanet Survey with a Forward Model Matched Filter
The Astrophysical Journal, Volume 842, p. 14
https://arxiv.org/abs/1705.05477
[SOU12]
Soummer et al. 2012
Detection and Characterization of Exoplanets and Disks Using Projections on Karhunen-Loève Eigenimages
The Astrophysical Journal Letters, Volume 755, Issue 2, p. 28
https://arxiv.org/abs/1207.4197
vip_hci.invprob.fmmf.fmmf(cube, pa, psf, fwhm, min_r=None, max_r=None, model='KLIP', var='FR', param={'delta_rot': 0.5, 'ncomp': 20, 'tolerance': 0.005}, crop=5, imlib='vip-fft', interpolation='lanczos4', nproc=1, verbose=True)[source]

Forward model matched filter generating SNR map and contrast map, using either KLIP or LOCI as PSF subtraction techniques, as implemented in [RUF17] and [DAH21a].

Parameters:
  • cube (numpy ndarray, 3d) – Input cube (ADI sequences), Dim 1 = temporal axis, Dim 2-3 = spatial axis
  • pa (numpy ndarray, 1d) – Parallactic angles for each frame of the ADI sequences.
  • psf (numpy ndarray 2d) – 2d array with the normalized PSF template, with an odd shape. The PSF image must be centered wrt to the array! Therefore, it is recommended to run the function normalize_psf to generate a centered and flux-normalized PSF template.
  • fwhm (int) – Full width at half maximum for the instrument PSF
  • min_r (int,optional) – Center radius of the first annulus considered in the FMMF detection map estimation. The radius should be larger than half the value of the ‘crop’ parameter . Default is None which corresponds to one FWHM.
  • max_r (int) – Center radius of the last annulus considered in the FMMF detection map estimation. The radius should be smaller or equal to half the size of the image minus half the value of the ‘crop’ parameter. Default is None which corresponds to half the size of the image minus half the value of the ‘crop’ parameter.
  • model (string, optional) – Selected PSF-subtraction technique for the computation of the FMMF detection map. FMMF work either with KLIP or LOCI. Default is ‘KLIP’.
  • var (str, optional) –

    Model used for the residual noise variance estimation used in the matched filtering (maximum likelihood estimation of the flux and SNR). Three different approaches are proposed: ‘FR’, ‘FM’, and ‘TE’:

    • ’FR’: consider the pixels in the selected annulus with a width equal to asize but separately for every frame.
    • ’FM’: consider the pixels in the selected annulus with a width equal to asize but separately for every frame. Apply a mask one FWHM on the selected pixel and its surrounding.
    • ’TE’: rely on the method developped in PACO to estimate the residual noise variance (take the pixels in a region of one FWHM arround the selected pixel, considering every frame in the derotated cube of residuals except for the selected frame)
  • param (dict, optional) –

    Dictionnary regrouping the parameters used by the KLIP (ncomp and delta_rot) or LOCI (tolerance and delta_rot) PSF-subtraction technique:

    • ncomp : int, optional. Number of components used for the low-rank approximation of the speckle field. Default is 20.
    • tolerance: float, optional. Tolerance level for the approximation of the speckle field via a linear combination of the reference images in the LOCI algorithm. Default is 5e-3.
    • delta_rot : float, optional. Factor for tunning the parallactic angle threshold, expressed in FWHM. Default is 0.5 (excludes 0.5xFHWM on each side of the considered frame).
  • crop (int, optional) – Part of the PSF template considered in the estimation of the FMMF detection map. Default is 5.
  • imlib (str, optional) – Parameter used for the derotation of the residual cube. See the documentation of the vip_hci.preproc.frame_rotate function.
  • interpolation (str, optional) – Parameter used for the derotation of the residual cube. See the documentation of the vip_hci.preproc.frame_rotate function.
  • nproc (int or None, optional) – Number of processes for parallel computing. By default (‘nproc=1’) the algorithm works in single-process mode. If set to None, nproc is automatically set to half the number of available CPUs.
  • verbose (bool, optional) – If True provide a message each time an annulus has been treated. Default True.
Returns:

  • flux_matrix (2d ndarray) – Maximum likelihood estimate of the contrast for each pixel in the field of view
  • snr_matrix (2d ndarray) – Signal to noise ratio map (defined as the estimated contrast divided by the estimated standard deviation of the contrast).

vip_hci.invprob.paco module

Implementation of the PACO algorithm for VIP, based on [FLA18].

Variable naming is based on the notation of [FLA18], see table 1 in the paper for a description.

Last updated 2022-05-09 by Evert Nasedkin (nasedkinevert@gmail.com).

[FLA18](1, 2, 3, 4, 5, 6, 7, 8, 9)
Flasseur et al. 2018
Exoplanet detection in angular differential imaging by statistical learning of the nonstationary patch covariances. The PACO algorithm
Astronomy & Astrophysics, Volume 618, p. 138
https://ui.adsabs.harvard.edu/abs/2018A%26A…618A.138F/abstract
class vip_hci.invprob.paco.FastPACO(cube: numpy.ndarray, angles: numpy.ndarray, psf: numpy.ndarray, dit_psf: Optional[float] = 1.0, dit_science: Optional[float] = 1.0, nd_transmission: Optional[float] = 1.0, fwhm: Optional[float] = 4.0, pixscale: Optional[float] = 1.0, rescaling_factor: Optional[float] = 1.0, verbose: Optional[bool] = False)[source]

Bases: vip_hci.invprob.paco.PACO

This class implements Algorithm 2 from [FLA18].

PACOCalc(phi0s: numpy.ndarray, use_subpixel_psf_astrometry: Optional[bool] = True, cpu: Optional[int] = 1) → None[source]

This function iterates of a list of test points (phi0) and a list of angles between frames to produce ‘a’ and b’, which can be used to generate a signal to noise map where SNR = b/sqrt(a) at each pixel.

Parameters:
  • phi0s (numpy.ndarray) – Array of (x,y) pixel locations to estimate companion position
  • use_subpixel_psf_astrometry (bool) – If true, the PSF model for each patch is shifted to the correct location as predicted by the starting location and the parallactic angles, before being resampled for the patch. If false, the PSF model is simply located at the center of each patch. Significantly improves performance if set to False, but the SNR is reduced.
  • cpu (int) – Number of cores to use for parallel processing
Returns:

  • a (numpy.ndarray) – a_l from Equation 15 of [FLA18]
  • b (numpy.ndarray) – b_l from Equation 16 of [FLA18]
compute_statistics_parallel(phi0s: numpy.ndarray, cpu: int) → Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

This function computes the mean and inverse covariance matrix for each patch in the image stack in parallel.

Parameters:
  • phi0s (int numpy.ndarray) – Array of pixel locations to estimate companion position
  • cpu (int) – Number of processors to use
Returns:

  • Cinv (numpy.ndarray) – Inverse covariance matrix between the the mean of each of the patches. The patches are a column through the time axis of the unrotated science images. Together with the mean this provides an empirical estimate of the background statistics. An inv covariance matrix is provided for each pixel location in ph0s.
  • m (numpy.ndarray) – Mean of each of the background patches along the time axis, for each pixel location in phi0s.
  • patch (numpy.ndarray) – The background column for each test pixel location in phi0s.
class vip_hci.invprob.paco.FullPACO(cube: numpy.ndarray, angles: numpy.ndarray, psf: numpy.ndarray, dit_psf: Optional[float] = 1.0, dit_science: Optional[float] = 1.0, nd_transmission: Optional[float] = 1.0, fwhm: Optional[float] = 4.0, pixscale: Optional[float] = 1.0, rescaling_factor: Optional[float] = 1.0, verbose: Optional[bool] = False)[source]

Bases: vip_hci.invprob.paco.PACO

Implementation of Algorithm 1 from [FLA18]

PACOCalc(phi0s: numpy.ndarray, use_subpixel_psf_astrometry: Optional[bool] = True, cpu: Optional[int] = 1) → None[source]

This function iterates of a list of test points (phi0) and a list of angles between frames to produce ‘a’ and b’, which can be used to generate a signal to noise map where SNR = b/sqrt(a) at each pixel.

Parameters:
  • phi0s (numpy.ndarray) – Array of (x,y) pixel locations to estimate companion position
  • use_subpixel_psf_astrometry (bool) – If true, the PSF model for each patch is shifted to the correct location as predicted by the starting location and the parallactic angles, before being resampled for the patch. If false, the PSF model is simply located at the center of each patch. Significantly improves performance if set to False, but the SNR is reduced.
  • cpu (int) – Number of cores to use for parallel processing. TODO: Not yet implemented.
Returns:

  • a (numpy.ndarray) – a_l from Equation 15 of [FLA18]
  • b (numpy.ndarray) – b_l from Equation 16 of [FLA18]

vip_hci.invprob.utils_andro module

Util functions for ANDROMEDA.

Module contents

Subpackage invprob aims to contain post-processing algorithms based on an inverse problem approach, such as ANDROMEDA [MUG09] / [CAN15], Foward Model Matched Filter [RUF17] / [DAH21a] or PACO [FLA18].