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.
- class vip_hci.invprob.andromeda.ANDROMEDA_Params(cube: ndarray | None = None, oversampling_fact: float | None = None, angle_list: ndarray | None = None, psf: ndarray | None = None, filtering_fraction: float = 0.25, min_sep: float = 0.5, annuli_width: float = 1.0, roa: float = 2, opt_method: Enum = OptMethod.LSQ, nsmooth_snr: int = 18, iwa: float | None = None, owa: float | None = None, precision: int = 50, fast: float | bool = False, homogeneous_variance: bool = True, ditimg: float = 1.0, ditpsf: float | None = None, tnd: float = 1.0, total: bool = False, multiply_gamma: bool = True, nproc: int = 1, verbose: bool = False)[source]
Bases:
object
Set of parameters for the ANDROMEDA algorithm.
See function andromeda below for the documentation.
- angle_list: ndarray = None
- annuli_width: float = 1.0
- cube: ndarray = None
- ditimg: float = 1.0
- ditpsf: float = None
- fast: float | bool = False
- filtering_fraction: float = 0.25
- homogeneous_variance: bool = True
- iwa: float = None
- min_sep: float = 0.5
- multiply_gamma: bool = True
- nproc: int = 1
- nsmooth_snr: int = 18
- opt_method: Enum = 'lsq'
- oversampling_fact: float = None
- owa: float = None
- precision: int = 50
- psf: ndarray = None
- roa: float = 2
- tnd: float = 1.0
- total: bool = False
- verbose: bool = False
- vip_hci.invprob.andromeda.andromeda(*all_args: List, **all_kwargs: dict)[source]
Exoplanet detection in ADI sequences by maximum-likelihood approach.
This is as implemented in [CAN15], itself inspired by the framework presented in [MUG09].
- Parameters:
all_args (list, optional) – Positionnal arguments for the andromeda algorithm. Full list of parameters below.
all_kwargs (dictionary, optional) – Mix of keyword arguments that can initialize a AndroParams or a AndroParams itself.
parameters (Andromeda)
----------
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
angle_list (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 to1
whenopt_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
. IfNone
, it is chosen automatically between the values0.5
,4
or0.25
. IDL parameter:IWA_INPUT
owa (float, optional) – Outer working angle / inner radius of the last annulus, expressed in
lambda/D
. IfNone
, 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
. IfTrue
, a value of20 lambda/D
is used,False
(the default) disables the fast mode entirely. Above this threshold, the annuli width is set to4*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 toNone
, the value ofditimg
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
(wasMAX
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.
- class vip_hci.invprob.fmmf.FMMF_Params(cube: ~numpy.ndarray | None = None, angle_list: ~numpy.ndarray | None = None, psf: ~numpy.ndarray | None = None, fwhm: float | None = None, min_r: int | None = None, max_r: int | None = None, model: str = 'KLIP', var: ~enum.Enum = VarEstim.FR, param: dict = <factory>, crop: int = 5, imlib: ~enum.Enum = Imlib.VIPFFT, interpolation: ~enum.Enum = Interpolation.LANCZOS4, nproc: int = 1, verbose: bool = True)[source]
Bases:
object
Set of parameters for the FMMF algorithm.
See function fmmf below for the documentation.
- angle_list: ndarray = None
- crop: int = 5
- cube: ndarray = None
- fwhm: float = None
- imlib: Enum = 'vip-fft'
- interpolation: Enum = 'lanczos4'
- max_r: int = None
- min_r: int = None
- model: str = 'KLIP'
- nproc: int = 1
- param: dict
- psf: ndarray = None
- var: Enum = 'fr'
- verbose: bool = True
- vip_hci.invprob.fmmf.fmmf(*all_args, **all_kwargs: dict)[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:
all_args (list, optional) – Positionnal arguments for the FMMF algorithm. Full list of parameters below.
all_kwargs (dictionary, optional) – Mix of keyword arguments that can initialize a FMMFParams or a FMMFParams itself.
cube (numpy ndarray, 3d) – Input cube (ADI sequences), Dim 1 = temporal axis, Dim 2-3 = spatial axis
angle_list (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 (Enum, see vip_hci.config.paramenum.VarEstim) – Model used for the residual noise variance estimation used in the matched filtering (maximum likelihood estimation of the flux and SNR).
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 (Enum, see vip_hci.config.paramenum.Imlib) – Parameter used for the derotation of the residual cube. See the documentation of the
vip_hci.preproc.frame_rotate
function.interpolation (Enum, see vip_hci.config.paramenum.Interpolation) – 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).
- class vip_hci.invprob.paco.FastPACO(cube: ndarray, angles: ndarray, psf: ndarray, dit_psf: float | None = 1.0, dit_science: float | None = 1.0, nd_transmission: float | None = 1.0, fwhm: float | None = 4.0, pixscale: float | None = 1.0, rescaling_factor: float | None = 1.0, verbose: bool | None = False)[source]
Bases:
PACO
This class implements Algorithm 2 from [FLA18].
- PACOCalc(phi0s: ndarray, use_subpixel_psf_astrometry: bool | None = True, cpu: int | None = 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:
- compute_statistics_parallel(phi0s: ndarray, cpu: int) Tuple[ndarray, ndarray, ndarray, 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: ndarray, angles: ndarray, psf: ndarray, dit_psf: float | None = 1.0, dit_science: float | None = 1.0, nd_transmission: float | None = 1.0, fwhm: float | None = 4.0, pixscale: float | None = 1.0, rescaling_factor: float | None = 1.0, verbose: bool | None = False)[source]
Bases:
PACO
Implementation of Algorithm 1 from [FLA18]
- PACOCalc(phi0s: ndarray, use_subpixel_psf_astrometry: bool | None = True, cpu: int | None = 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:
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].