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.
- 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_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.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.utils_stats module
Various stat functions.
- 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.
- 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.
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.