vip_hci.stats package¶
Submodules¶
vip_hci.stats.bkg_proba module¶
Probability of a point source to be a background star.
-
vip_hci.stats.bkg_proba.
bkg_star_proba
(n_dens, sep, n_bkg=1, verbose=True, full_output=False)[source]¶ Given an input density of background star brighter than a certain magnitude (obtained e.g. from the Besancon model or TRILEGAL), and the separation of n_bkg point source, estimate the probability of having n_bkg or more background stars in a disk with radius equal to the largest separation. The probability is estimated using a spatial Poisson point process.
Parameters: - n_dens (float) – Number density of background stars in the direction of the object of interest, in arcsec^-2.
- sep (float or numpy 1d array) – Separation of the point sources with respect to central star, in arcsec.
- n_bkg (int, opt) – Number of point sources in the field, and for which the separation is provided.
- verbose (bool, opt) – Whether to print the probabilities for 0 to n_bkg point sources.
- full_output (bool, opt) – Whether to also return probabilities of 0 to n_bkg-1 point sources
Returns: - proba (float) – Probability between 0% and 100%.
- [probas (np 1d array] if full_output is True) – Probabilities of getting 0 to n_bkg-1 point sources
vip_hci.stats.clip_sigma module¶
Module with sigma clipping functions.
-
vip_hci.stats.clip_sigma.
clip_array
(array, lower_sigma, upper_sigma, bpm_mask_ori=None, out_good=False, neighbor=False, num_neighbor=3, mad=False, half_res_y=False)[source]¶ Sigma clipping for detecting outlying values in 2d array. If the parameter ‘neighbor’ is True the clipping can be performed in a local patch around each pixel, whose size depends on ‘neighbor’ parameter.
Parameters: - array (numpy ndarray) – Input 2d array, image.
- lower_sigma (float) – Value for sigma, lower boundary.
- upper_sigma (float) – Value for sigma, upper boundary.
- bpm_mask_ori (2d numpy ndarray or None) – Known (static) bad pixels. Additional bad pixels will be identified, on top of those ones. They are not considered as good neighbours during sigma-clipping.
- out_good (bool, optional) – For choosing different outputs. True to return indices of good pixels, False for indices of bad pixels.
- neighbor (bool, optional) – For clipping over the median of the contiguous pixels.
- num_neighbor (int, optional) – The side of the window around each pixel where the sigma and median are calculated. If half_res_y, this is the horizontal side (the vertical side will be twice smaller).
- mad ({False, True}, bool optional) – If True, the median absolute deviation will be used instead of the standard deviation.
- min_std (float, optional) – Min standard deviation considered for the lower and upper sigma conditions. Can be useful for frames with padded edges (e.g. SPHERE/IFS)
- half_res_y (bool, optional) – Whether the input data have every couple of 2 rows identical, i.e. there is twice less angular resolution vertically than horizontally (e.g. SINFONI data).
Returns: - good (array_like) – If out_good argument is true, returns the indices of not-outlying px.
- bad (array_like) – If out_good argument is false, returns a vector with the outlier px.
-
vip_hci.stats.clip_sigma.
sigma_filter
(frame_tmp, bpix_map, neighbor_box=3, min_neighbors=3, half_res_y=False, verbose=False)[source]¶ Sigma filtering of pixels in a 2d array.
Parameters: - frame_tmp (numpy ndarray) – Input 2d array, image.
- bpix_map (numpy ndarray) – Input array of the same size as frame_tmp, indicating the locations of bad/nan pixels by 1 (the rest of the array is set to 0)
- neighbor_box (int, optional) – The side of the window around each pixel where the sigma and median are calculated. If half_res_y, this is the horizontal side (the vertical side will be twice smaller).
- min_neighbors (int, optional) – Minimum number of good neighboring pixels to be able to correct the bad/nan pixels
- half_res_y (bool, optional) – Whether the input data have every couple of 2 rows identical, i.e. there is twice less angular resolution vertically than horizontally (e.g. SINFONI data).
- verbose (bool, optional) – Whether to print more information while running.
Returns: frame_corr – Output array with corrected bad/nan pixels
Return type: numpy ndarray
vip_hci.stats.distances module¶
Distance and correlation between images.
[WAN04] | Wang et al. 2004
Image Quality Assessment: From Error Visibility to Structural
Similarity
IEEE Transactions on Image Processing, Volume 13, Issue 4, pp. 600-612
|
[GRE16] | Greco & Brandt 2016
The Measurement, Treatment, and Impact of Spectral Covariance and
Bayesian Priors in Integral-field Spectroscopy of Exoplanets
The Astrophysical Journal, Volume 833, Issue 1, p. 134
|
-
vip_hci.stats.distances.
cube_distance
(array, frame, mode='full', dist='sad', inradius=None, width=None, mask=None, plot=True)[source]¶ Computes the distance (or similarity) between frames in a cube, using one as the reference (it can be either a frame from the same cube or a separate 2d array). Depending on the mode, the whole image can be used, or just the pixels in a given annulus. The criteria used are: - the Manhattan distance (SAD or sum of absolute differences), - the Euclidean distance (square root of the sum of the squared differences), - the Mean Squared Error, - the Spearman rank correlation coefficient, - the Pearson correlation coefficient, - the Structural Similarity Index (SSIM).
The SAD, MSE and Ecuclidean criteria are dissimilarity criteria, which means that 0 is perfect similarity. The Pearson (resp. Spearman) coefficients, vary between -1 and +1 with 0 implying no correlation. Correlations of -1 or +1 imply an exact linear (resp. monotonic) relationship. The Structural Similarity Index was proposed in [WAN04]. SSIM varies between -1 and 1, where 1 means perfect similarity. SSIM attempts to model the perceived change in the structural information of the image. The mean SSIM is reported.
Parameters: - array (numpy ndarray) – Input cube or 3d array.
- frame (int, 2d array or None) – Reference frame in the cube or 2d array. If None, will take the median frame of the 3d array.
- mode ({'full','annulus', 'mask'}, string optional) – Whether to use the full frames, a centered annulus or a provided mask.
- dist ({'sad','euclidean','mse','pearson','spearman', 'ssim'}, str optional) – Which criterion to use.
- inradius (None or int, optional) – The inner radius when mode is ‘annulus’.
- width (None or int, optional) – The width when mode is ‘annulus’.
- mask (2d array, optional) – If mode is ‘mask’, this is the mask within which the metrics is calculated in the images.
- plot (bool, optional) – Whether to plot the distances or not.
Returns: lista – 1d array of distances for each frame wrt the reference one.
Return type: numpy ndarray
-
vip_hci.stats.distances.
spectral_correlation
(array, ann_width=2, r_in=1, r_out=None, pl_xy=None, mask_r=4, fwhm=4, sp_fwhm_guess=3, full_output=False)[source]¶ Computes the spectral correlation between (post-processed) IFS frames, as a function of radius, implemented as Eq. 7 of [GRE16]. This is a crucial step for an unbias fit of a measured IFS spectrum to either synthetic or template spectra.
Parameters: - array (numpy ndarray) – Input cube or 3d array, of dimensions n_ch x n_y x n_x; where n_y and n_x should be odd values (star should be centered on central pixel).
- ann_width (int, optional) – Width in pixels of the concentric annuli used to compute the spectral correlation as a function of radial separation. Greco & Brandt 2017 noted no significant differences for annuli between 1 and 3 pixels width on GPI data.
- r_in (int, optional) – Innermost radius where the spectral correlation starts to be computed.
- r_out (int, optional) – Outermost radius where the spectral correlation is computed.If left as None, it will automatically be computed up to the edge of the frame.
- pl_xy (tuple of tuples of 2 floats, optional) – x,y coordiantes of all companions present in the images. If provided, a circle centered on the location of each companion will be masked out for the spectral correlation computation.
- mask_r (float, optional) – if pl_xy is provided, this should also be provided. Size of the aperture around each companion (in terms of fwhm) that is discarded to not bias the spectral correlation computation.
- fwhm (float, optional) – if pl_xy is provided, this should also be provided. By default we consider a 2FWHM aperture mask around each companion to not bias the spectral correlation computation.
- sp_fwhm_guess (float, optional) – Initial guess on the spectral FWHM of all channels.
- full_output (bool, opt) – Whether to also output the fitted spectral FWHM for each channel.
- Note (radii that are skipped will be filled with zeros in the output cube.) –
Returns: - sp_corr (numpy ndarray) – 3d array of spectral correlation, as a function of radius with dimensions: n_r x n_ch x n_ch, where n_r = min((n_y-1)/2,(n_x-1)/2) Starts at r = 1 (not r=0) px.
- sp_fwhm (numpy ndarray) – (if full_output is True) 2d array containing the spectral fwhm at each radius, for each spectral channel. Dims: n_r x n_ch
vip_hci.stats.im_stats module¶
Module for image statistics.
-
vip_hci.stats.im_stats.
frame_histo_stats
(image_array, plot=True)[source]¶ Plots a frame with a colorbar, its histogram and some statistics: mean, median, maximum, minimum and standard deviation values.
Parameters: - image_array (numpy ndarray) – The input frame.
- plot (bool, optional) – If True plots the frame and the histogram with the values.
Returns: - mean (float) – Mean value of array.
- median (float) – Median value of array.
- std (float) – Standard deviation of array.
- maxim (int or float) – Maximum value.
- minim (int or float) – Minimum value.
-
vip_hci.stats.im_stats.
frame_average_radprofile
(frame, sep=1, init_rad=None, subtr_profile=False, plot=True)[source]¶ Calculates the average radial profile of an image.
Parameters: - frame (numpy ndarray) – Input image or 2d array.
- sep (int, optional) – The average radial profile is recorded every
sep
pixels. - init_rad (int, optional) – Initial radius in pixels from the center of the image to begin calculating the average radial profile.
- subtr_profile (boolean, optional) – If True, the average radial profile is subtracted from the frame and returned as a second output. Inner mask is applied if init_rad is provided.
- plot (bool, optional) – If True, the profile is plotted.
Returns: - df (dataframe) – Pandas dataframe with the radial profile and distances.
- subtr_frame (numpy ndarray, 2d) – [subtr_profile=True] Frame with the radial profile subtracted.
vip_hci.stats.utils_stats module¶
Various stat functions.
-
vip_hci.stats.utils_stats.
descriptive_stats
(array, verbose=True, label='', mean=False, plot=False)[source]¶ Simple statistics from vector.
-
vip_hci.stats.utils_stats.
frame_basic_stats
(arr, region='circle', radius=5, xy=None, inner_radius=0, size=5, plot=True, full_output=False)[source]¶ Calculates statistics in a
region
of a 2D array.Parameters: - arr (numpy ndarray) – Input array.
- region ({'circle', 'annulus'}, str optional) – Pixels are extracted either from a centered annulus or a circular
aperture centered on
xy
. - radius (int) – Radius of the circular aperture.
- xy (tuple of ints) – Coordinates of the center of the circular aperture.
- inner_radius (int) – Annulus inner radius of the annulus.
- size (int) – Width of the annulus.
- plot (bool, optional) – If True it plots the histogram and the region.
- full_output (bool, optional) – If true it returns mean, std_dev, median, if false just the mean.
Returns: - If full_out is true it returns the sum, mean, std_dev, median. If false
- only the mean.
-
vip_hci.stats.utils_stats.
cube_basic_stats
(arr, region='circle', radius=5, xy=None, inner_radius=0, size=5, plot=False, full_output=False)[source]¶ Calculates statistics in a region on a 3D array and plots the variation of the mean, median and standard deviation as a functions of time.
Parameters: - arr (numpy ndarray) – Input array.
- region ({'circle', 'annulus'}, str optional) – Pixels are extracted either from a centered annulus or a circular
aperture centered on
xy
. - radius (int) – Radius of the circular aperture.
- xy (tuple of ints) – Coordinates of the center of the circular aperture.
- inner_radius (int) – Annulus inner radius of the annulus.
- size (int) – Width of the annulus.
- plot (bool, optional) – If True it plots the mean, std_dev and max. Also the histogram.
- full_output (bool, optional) – If true it returns mean, std_dev, median, if false just the mean.
Returns: - If full_out is true it returns the sum, mean, std_dev, median. If false
- only the mean.
Module contents¶
Subpackage stats
contains functionalities such as:
- extracting statistics (mean, median, std dev, sum) in regions of a frame or cube,
- median absolute deviation,
- sigma filtering of pixels in frames,
- distance (correlation) between the frames in a cube,
- distance (correlation) between a cube and a reference frame.