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.