vip_hci.objects package

Submodules

vip_hci.objects.dataset module

Module with Dataset and Frame classes.

class vip_hci.objects.dataset.Dataset(cube, hdu=0, angles=None, wavelengths=None, fwhm=None, px_scale=None, psf=None, psfn=None, cuberef=None)

Bases: Saveable

High-contrast imaging dataset class.

Parameters:

• cube (str or numpy array) – 3d or 4d high-contrast image sequence. If a string is provided, cube is interpreted as the path of the FITS file containing the sequence.

• hdu (int, optional) – If cube is a String, hdu indicates the HDU from the FITS file. By default the first HDU is used.

• angles (list or numpy array, optional) – The vector of parallactic angles.

• wavelengths (list or numpy array, optional) – The vector of wavelengths (to be used as scaling factors).

• fwhm (float, optional) – The FWHM associated with this dataset (instrument dependent). Required for several methods (operations on the cube).

• px_scale (float, optional) – The pixel scale associated with this dataset (instrument dependent).

• psf (numpy array, optional) – The PSF template associated with this dataset.

• psfn (numpy array, optional) – Normalized/cropped/centered version of the PSF template associated with this dataset.

• cuberef (str or numpy array) – 3d or 4d high-contrast image sequence. To be used as a reference cube.

collapse(mode='median', n=50)

Collapsing the sequence into a 2d array.

copy(deep=True, check_mem=True)

Create an in-memory copy of this Dataset.

This is especially useful for keeping a backup copy of the original dataset before modifying if (e.g. with injections).

Parameters:

• deep (bool, optional) – By default, a deep copy is created. That means every (sub)attribute is copied in memory. While this requires more memory, one can safely modify the attributes without touching the original Dataset. When deep=False, a shallow copy of the Dataset is returned instead. That means all attributes (e.g. self.cube) point back to the original object’s attributes. Pay attention when modifying such a shallow copy!

• check_mem (bool, optional) – [deep=True] If True, verifies that the system has enough memory to store the result.

Returns:

new_dataset – (deep) copy of this Dataset.

Return type:

Dataset

crop_frames(size, xy=None, force=False)

Crop the frames of the sequence (3d or 4d cube).

Parameters:

• size (int) – New size of the (square) frames.

• xy (tuple of ints) – X, Y coordinates of new frame center. If you are getting the coordinates from ds9 subtract 1, python has 0-based indexing.

• force (bool, optional) – Size and the original size of the frames must be both even or odd. With force set to True this condition can be avoided.

derotate(imlib='vip-fft', interpolation='lanczos4', cxy=None, nproc=1, border_mode='constant', mask_val=nan, edge_blend=None, interp_zeros=False, ker=1)

Derotating the frames of the sequence according to the parallactic angles.

Parameters:

• imlib ({'opencv', 'skimage', 'vip-fft'}, str optional) – Library used for image transformations. Opencv is faster than ndimage or skimage.

• interpolation (str, optional) – For ‘skimage’ library: ‘nearneig’, bilinear’, ‘bicuadratic’, ‘bicubic’, ‘biquartic’, ‘biquintic’. The ‘nearneig’ interpolation is the fastest and the ‘biquintic’ the slowest. The ‘nearneig’ is the poorer option for interpolation of noisy astronomical images. For ‘opencv’ library: ‘nearneig’, ‘bilinear’, ‘bicubic’, ‘lanczos4’. The ‘nearneig’ interpolation is the fastest and the ‘lanczos4’ the slowest and accurate. ‘lanczos4’ is the default.

• cxy (tuple of int, optional) – Coordinates X,Y of the point with respect to which the rotation will be performed. By default the rotation is done with respect to the center of the frames, as it is returned by the function vip_hci.var.frame_center.

• nproc (int, optional) – Whether to rotate the frames in the sequence in a multi-processing fashion. Only useful if the cube is significantly large (frame size and number of frames).

• border_mode (str, optional) – See the documentation of the vip_hci.preproc.frame_rotate function.

• mask_val (float, optional) – See the documentation of the vip_hci.preproc.frame_rotate function.

• edge_blend (str, optional) – See the documentation of the vip_hci.preproc.frame_rotate function.

• interp_zeros (str, optional) – See the documentation of the vip_hci.preproc.frame_rotate function.

• ker (int, optional) – See the documentation of the vip_hci.preproc.frame_rotate function.

drop_frames(n, m, verbose=True)

Slice the cube so that all frames between n``and ``m are kept.

The indices n and m are included and 1-based.

Examples

For a cube which has 5 frames numbered 1, 2, 3, 4, 5, calling ds.drop_frames(2, 4) would result in the frames 2, 3, 4 to be kept, so the first and the last frame would be discarded.

filter(method, mode, median_size=5, kernel_size=5, fwhm_size=5, btw_cutoff=0.2, btw_order=2, hann_cutoff=5, gauss_mode='conv', verbose=True)

High/low pass filtering the frames of the cube.

Parameters:

• method ({'lp', 'hp'}) – Low-pass or high-pass filtering.

• mode (str) –

  Type of low/high-pass filtering. median

  [lp] applies a median low-pass filter to the image.

  gauss

  [lp] applies a Gaussian low-pass filter to the image.

  laplacian

  [hp] applies a Laplacian filter with kernel size defined by kernel_size using the Opencv library.

  laplacian-conv

  [hp] applies a Laplacian high-pass filter by defining a kernel (with kernel_size) and using the convolve_fft Astropy function.

  median-subt

  [hp] subtracts a median low-pass filtered version of the image.

  gauss-subt

  [hp] subtracts a Gaussian low-pass filtered version of the image.

  fourier-butter

  [hp] applies a high-pass 2D Butterworth filter in Fourier domain.

  hann

  [hp] uses a Hann window.

• median_size (int, optional) – Size of the median box for the median or median-subt filter.

• kernel_size (int, optional) – Size of the Laplacian kernel used in laplacian mode. It must be a positive odd integer value.

• fwhm_size (float, optional) – Size of the Gaussian kernel used in gauss or gauss-subt mode.

• btw_cutoff (float, optional) – Frequency cutoff for low-pass 2d Butterworth filter used in fourier-butter mode.

• btw_order (int, optional) – Order of low-pass 2d Butterworth filter used in fourier-butter mode.

• hann_cutoff (float) – Frequency cutoff for the hann mode.

• gauss_mode ({'conv', 'convfft'}, str optional) – ‘conv’ uses the multidimensional gaussian filter from scipy.ndimage and ‘convfft’ uses the fft convolution with a 2d Gaussian kernel.

frame_distances(frame, region='full', dist='sad', inner_radius=None, width=None, plot=True)

Calculate the frame distance/correlation with respect to a reference image.

Parameters:

• frame (int or 2d array) – Reference frame in the cube or 2d array.

• region ({'full', 'annulus'}, string optional) – Whether to use the full frames or a centered annulus.

• dist ({'sad','euclidean','mse','pearson','spearman', 'ssim'}, str optional) – Which criterion to use.

• inner_radius (None or int, optional) – The inner radius when mode is ‘annulus’.

• width (None or int, optional) – The width when mode is ‘annulus’.

• plot (bool, optional) – Whether to plot the distances or not.

frame_stats(region='circle', radius=5, xy=None, annulus_inner_radius=0, annulus_width=5, wavelength=0, plot=True)

Calculate statistics on a region of each image of the sequence.

The region can be a circular aperture or an annulus.

Parameters:

• region ({'circle', 'annulus'}, str optional) – Region in which basic statistics (mean, stddev, median and max) are calculated.

• radius (int, optional) – Radius of the circular aperture.

• xy (tuple of floats, optional) – Center of the circular aperture.

• annulus_inner_radius (int, optional) – Inner radius of the annular region.

• annulus_width (int, optional) – Width of the annular region.

• wavelength (int, optional) – Index of the wavelength to be analyzed in the case of a 4d cube.

• plot (bool, optional) – Whether to plot the frame, histograms and region.

generate_copies_with_injections(n_copies, inrad=8, outrad=12, dist_flux=('uniform', 2, 500))

Create copies of this dataset, containing different random injections.

Parameters:

• n_copies (int) – This is the number of ‘cube copies’ returned.

• inrad (float) – Inner and outer radius of the injections. The actual injection position is chosen randomly.

• outrad (float) – Inner and outer radius of the injections. The actual injection position is chosen randomly.

• dist_flux (tuple(‘method’, *params)) –

  Tuple describing the flux selection. Method can be a function, the *params are passed to it. Method can also be a string, for a pre-defined random function:

  ('skewnormal', skew, mean, var)

  uses scipy.stats.skewnorm.rvs

  ('uniform', low, high)

  uses np.random.uniform

  ('normal', loc, scale)

  uses np.random.normal

Yields:

fake_dataset (Dataset) – Copy of the original Dataset, with injected companions.

get_nbytes()

Return the total number of bytes the Dataset consumes.

inject_companions(flux, rad_dists, n_branches=1, theta=0, imlib='vip-fft', interpolation='lanczos4', full_output=False, verbose=True)

Inject fake companions in 3d or 4d cubes.

Parameters:

• flux (float or list) – Factor for controlling the brightness of the fake companions.

• rad_dists (float, list or array 1d) – Vector of radial distances of fake companions in pixels.

• n_branches (int, optional) – Number of azimutal branches.

• theta (float, optional) – Angle in degrees for rotating the position of the first branch that by default is located at zero degrees. Theta counts counterclockwise from the positive x axis.

• imlib ({'opencv', 'ndimage-fourier', 'ndimage-interp', 'vip-fft'}, str opt) – Library or method used for performing the image shift. ‘ndimage-fourier’, does a fourier shift operation and preserves better the pixel values (therefore the flux and photometry). Interpolation based shift (‘opencv’ and ‘ndimage-interp’) is faster than the fourier shift. ‘opencv’ is recommended when speed is critical.

• interpolation ({'bicubic', 'bilinear', 'nearneig'}, optional) – Only used in case of imlib is set to ‘opencv’ or ‘ndimage-interp’, where the images are shifted via interpolation. For ‘ndimage-interp’ library: ‘nearneig’, bilinear’, ‘bicuadratic’, ‘bicubic’, ‘biquartic’, ‘biquintic’. The ‘nearneig’ interpolation is the fastest and the ‘biquintic’ the slowest. The ‘nearneig’ is the poorer option for interpolation of noisy astronomical images. For ‘opencv’ library: ‘nearneig’, ‘bilinear’, ‘bicubic’, ‘lanczos4’. The ‘nearneig’ interpolation is the fastest and the ‘lanczos4’ the slowest and accurate. ‘lanczos4’ is the default.

• full_output (bool, optional) – Return the coordinates of the injected companions.

• verbose (bool, optional) – If True prints out additional information.

Returns:

yx – [full_output=True] Pixel coordinates of the injections in the first frame (and first wavelength for 4D cubes). These are only the new injections - all injections (from multiple calls to this function) are stored in self.injections_yx.

Return type:

list of tuple(y,x)

load_angles(angles, hdu=0)

Load the PA vector from a FITS file. It is possible to specify the HDU.

Parameters:

• angles (str or 1d numpy ndarray) – List or vector with the parallactic angles.

• hdu (int, optional) – If angles is a String, hdu indicates the HDU from the FITS file. By default the first HDU is used.

load_wavelengths(wavelengths, hdu=0)

Load the scaling factors vector from a FITS file.

It is possible to specify the HDU.

Parameters:

• wavelengths (str or 1d numpy ndarray) – List or vector with the wavelengths.

• hdu (int, optional) – If wavelengths is a String, hdu indicates the HDU from the FITS file. By default the first HDU is used.

mask_center(radius, fillwith=0, mode='in')

Mask the values inside/outside a centered circular aperture.

Parameters:

• radius (int) – Radius of the circular aperture.

• fillwith (int, float or np.nan, optional) – Value to put instead of the masked out pixels.

• mode ({'in', 'out'}, optional) – When set to ‘in’ then the pixels inside the radius are set to fillwith. When set to ‘out’ the pixels outside the circular mask are set to fillwith.

normalize_psf(fit_fwhm=True, size=None, threshold=None, mask_core=None, model='gauss', imlib='vip-fft', interpolation='lanczos4', force_odd=True, verbose=True)

Normalize a PSF (2d or 3d array), to have the flux in a 1xFWHM aperture = 1.

Also allows to crop the array and center the PSF at the center of the frame(s).

Parameters:

• fit_fwhm (bool, optional) – Whether to fit a model to estimate the FWHM instead of using the self.fwhm attribute.

• size (int or None, optional) – If int it will correspond to the size of the squared subimage to be cropped form the psf array.

• threshold (None of float, optional) – Sets to zero small values, trying to leave only the core of the PSF.

• mask_core (None of float, optional) – Sets the radius of a circular aperture for the core of the PSF, everything else will be set to zero.

• imlib ({'opencv', 'ndimage-fourier', 'ndimage-interp', 'vip-fft'}, str opt) – Library or method used for performing the image shift. ‘ndimage-fourier’, does a fourier shift operation and preserves better the pixel values (therefore the flux and photometry). Interpolation based shift (‘opencv’ and ‘ndimage-interp’) is faster than the fourier shift. ‘opencv’ is recommended when speed is critical.

• interpolation ({'bicubic', 'bilinear', 'nearneig'}, optional) – Only used in case of imlib is set to ‘opencv’ or ‘ndimage-interp’, where the images are shifted via interpolation. For ‘ndimage-interp’ library: ‘nearneig’, bilinear’, ‘bicuadratic’, ‘bicubic’, ‘biquartic’, ‘biquintic’. The ‘nearneig’ interpolation is the fastest and the ‘biquintic’ the slowest. The ‘nearneig’ is the poorer option for interpolation of noisy astronomical images. For ‘opencv’ library: ‘nearneig’, ‘bilinear’, ‘bicubic’, ‘lanczos4’. The ‘nearneig’ interpolation is the fastest and the ‘lanczos4’ the slowest and accurate. ‘lanczos4’ is the default.

• force_odd (str, optional) – If True the resulting array will have odd size (and the PSF will be placed at its center). If False, and the frame size is even, then the PSF will be put at the center of an even-sized frame.

• verbose (bool, optional) – If True intermediate results are printed out.

plot(**kwargs)

Plot the frames of a 3D or 4d cube.

Parameters:

**kwargs (dict, optional) – Parameters passed to the function plot_cubes of the package HCIplot.

recenter(method='2dfit', xy=None, subi_size=5, model='gauss', nproc=1, imlib='vip-fft', interpolation='lanczos4', offset=None, negative=False, threshold=False, save_shifts=False, cy_1=None, cx_1=None, upsample_factor=100, alignment_iter=5, gamma=1, min_spat_freq=0.5, max_spat_freq=3, recenter_median=False, sigfactor=6, cropsize=101, hsize=0.4, step=0.01, mask_center=None, verbose=True, debug=False, plot=True)

Recenter frame-to-frame.

Parameters:

• method ({'2dfit', 'dftups', 'dftupspeckles', 'satspots', 'radon'}, optional) – Recentering method.

• xy (tuple or ints or tuple of 4 tuples of ints, optional) – For the 2dfitting, xy are the coordinates of the center of the subimage (wrt the original frame). For the satellite spots method, it is a tuple with coordinates X,Y of the 4 satellite spots. When the spots are in an X configuration, the order is the following: top-left, top-right, bottom-left and bottom-right. When the spots are in an + (cross-like) configuration, the order is the following: top, right, left, bottom.

• subi_size (int, optional) – Size of the square subimage sides in pixels.

• model (str, optional) – [method=2dfit] Sets the type of fit to be used. ‘gauss’ for a 2d Gaussian fit and ‘moff’ for a 2d Moffat fit.

• nproc (int or None, optional) – Number of processes (>1) for parallel computing. If 1 then it runs in serial. If None the number of processes will be set to (cpu_count()/2).

• imlib ({'opencv', 'ndimage-fourier', 'ndimage-interp', 'vip-fft'}, str opt) – Library or method used for performing the image shift. ‘ndimage-fourier’, does a fourier shift operation and preserves better the pixel values (therefore the flux and photometry). Interpolation based shift (‘opencv’ and ‘ndimage-interp’) is faster than the fourier shift. ‘opencv’ is recommended when speed is critical.

• interpolation ({'bicubic', 'bilinear', 'nearneig'}, optional) – Only used in case of imlib is set to ‘opencv’ or ‘ndimage-interp’, where the images are shifted via interpolation. For ‘ndimage-interp’ library: ‘nearneig’, bilinear’, ‘bicuadratic’, ‘bicubic’, ‘biquartic’, ‘biquintic’. The ‘nearneig’ interpolation is the fastest and the ‘biquintic’ the slowest. The ‘nearneig’ is the poorer option for interpolation of noisy astronomical images. For ‘opencv’ library: ‘nearneig’, ‘bilinear’, ‘bicubic’, ‘lanczos4’. The ‘nearneig’ interpolation is the fastest and the ‘lanczos4’ the slowest and accurate. ‘lanczos4’ is the default.

• offset (tuple of floats, optional) – [method=2dfit] If None the region of the frames used for the 2d Gaussian/Moffat fit is shifted to the center of the images (2d arrays). If a tuple is given it serves as the offset of the fitted area wrt the center of the 2d arrays.

• negative (bool, optional) – [method=2dfit/dftups/dftupspeckles] If True a negative 2d Gaussian/Moffat fit is performed.

• threshold (bool, optional) – [method=2dfit] If True the background pixels (estimated using sigma clipped statistics) will be replaced by small random Gaussian noise.

• save_shifts (bool, optional) – [method=2dfit/dftups] Whether to save the shifts to a file in disk.

• cy_1 (int, optional) – [method=dftups] Coordinates of the center of the subimage for fitting a 2d Gaussian and centroiding the 1st frame.

• cx_1 (int, optional) – [method=dftups] Coordinates of the center of the subimage for fitting a 2d Gaussian and centroiding the 1st frame.

• upsample_factor (int, optional) – [method=dftups] Upsampling factor (default 100). Images will be registered to within 1/upsample_factor of a pixel.

• alignment_iter (int, optional) – [method=dftupspeckles] Number of alignment iterations (recomputes median after each iteration).

• gamma (int, optional) – [method=dftupspeckles] Applies a gamma correction to emphasize speckles (useful for faint stars).

• min_spat_freq (float, optional) – [method=dftupspeckles] Spatial frequency for high pass filter.

• max_spat_freq (float, optional) – [method=dftupspeckles] Spatial frequency for low pass filter.

• recenter_median (bool, optional) – [method=dftupspeckles] Recenter the frames at each iteration based on the gaussian fit.

• sigfactor (int, optional) – [method=satspots] The background pixels will be thresholded before fitting a 2d Gaussian to the data using sigma clipped statistics. All values smaller than (MEDIAN + sigfactor*STDDEV) will be replaced by small random Gaussian noise.

• cropsize (odd int, optional) – [method=radon] Size in pixels of the cropped central area of the input array that will be used. It should be large enough to contain the satellite spots.

• hsize (float, optional) – [method=radon] Size of the box for the grid search. The frame is shifted to each direction from the center in a hsize length with a given step.

• step (float, optional) – [method=radon] The step of the coordinates change.

• mask_center (None or int, optional) – [method=radon] If None the central area of the frame is kept. If int a centered zero mask will be applied to the frame. By default the center isn’t masked.

• verbose (bool, optional) – Whether to print to stdout the timing and aditional info.

• debug (bool, optional) – If True debug information is printed and plotted.

• plot (bool, optional) – Whether to plot the shifts.

remove_badframes(method='corr', frame_ref=None, crop_size=30, dist='pearson', percentile=20, stat_region='annulus', inner_radius=10, width=10, top_sigma=1.0, low_sigma=1.0, window=None, roundlo=-0.2, roundhi=0.2, lambda_ref=0, plot=True, verbose=True)

Find outlying/bad frames and slice the cube accordingly.

Besides modifying self.cube and self.angles, also sets a self.good_indices which contain the indices of the angles which were kept.

Parameters:

• method ({'corr', 'pxstats', 'ellip'}, optional) – Method which is used to determine bad frames. Refer to the preproc.badframes submodule for explanation of the different methods.

• frame_ref (int, 2d array or None, optional) – [method=corr] Index of the frame that will be used as a reference or 2d reference array.

• crop_size (int, optional) – [method=corr] Size in pixels of the square subframe to be analyzed.

• dist ({'sad','euclidean','mse','pearson','spearman'}, optional) – [method=corr] One of the similarity or dissimilarity measures from function vip_hci.stats.distances.cube_distance().

• percentile (float, optional) – [method=corr] The percentage of frames that will be discarded [0..100].

• stat_region ({'annulus', 'circle'}, optional) – [method=pxstats] Whether to take the statistics from a circle or an annulus.

• inner_radius (int, optional) – [method=pxstats] If stat_region is ‘annulus’ then ‘in_radius’ is the inner radius of the annular region. If stat_region is ‘circle’ then ‘in_radius’ is the radius of the aperture.

• width (int, optional) – [method=pxstats] Size of the annulus. Ignored if mode is ‘circle’.

• top_sigma (int, optional) – [method=pxstats] Top boundary for rejection.

• low_sigma (int, optional) – [method=pxstats] Lower boundary for rejection.

• window (int, optional) – [method=pxstats] Window for smoothing the median and getting the rejection statistic.

• roundlo (float, optional) – [method=ellip] : Lower and higher bounds for the ellipticipy.

• roundhi (float, optional) – [method=ellip] : Lower and higher bounds for the ellipticipy.

• lambda_ref (int, optional) – [4D cube] Which wavelength to consider when determining bad frames on a 4D cube.

• plot (bool, optional) – If true it plots the mean fluctuation as a function of the frames and the boundaries.

• verbose (bool, optional) – Show debug output.

rescale(scale, imlib='ndimage', interpolation='bicubic', verbose=True)

Resample the pixels (upscaling or downscaling the frames).

Parameters:

• scale (int, float or tuple) – Scale factor for upsampling or downsampling the frames in the cube. If a tuple it corresponds to the scale along x and y.

• imlib ({'ndimage', 'opencv', 'vip-fft'}, str optional) – Library used for image transformations. ndimage is the default.

• interpolation (str, optional) – For ‘ndimage’ library: ‘nearneig’, bilinear’, ‘bicuadratic’, ‘bicubic’, ‘biquartic’, ‘biquintic’. The ‘nearneig’ interpolation is the fastest and the ‘biquintic’ the slowest. The ‘nearneig’ is the worst option for interpolation of noisy astronomical images. For ‘opencv’ library: ‘nearneig’, ‘bilinear’, ‘bicubic’, ‘lanczos4’. The ‘nearneig’ interpolation is the fastest and the ‘lanczos4’ the slowest and accurate.

• verbose (bool, optional) – Whether to print out additional info such as the new cube shape.

subsample(window, mode='mean')

Sumb-sample temporally the sequence (3d or 4d cube).

Parameters:

• window (int) – Window for mean/median.

• mode ({'mean', 'median'}, optional) – Switch for choosing mean or median.

class vip_hci.objects.dataset.Frame(data, hdu=0, fwhm=None)

Bases: object

High-contrast imaging frame (2d array).

Parameters:

• data (numpy ndarray) – 2d array.

• hdu (int, optional) – If cube is a String, hdu indicates the HDU from the FITS file. By default the first HDU is used.

• fwhm (float, optional) – The FWHM associated with this dataset (instrument dependent). Required for several methods (operations on the cube).

crop(size, xy=None, force=False)

Cropping the frame.

Parameters:

• size (int, odd) – Size of the subframe.

• cenxy (tuple, optional) – Coordinates of the center of the subframe.

• force (bool, optional) – Size and the size of the 2d array must be both even or odd. With force set to True this condition can be avoided.

detect_blobs(psf, bkg_sigma=1, method='lpeaks', matched_filter=False, mask=True, snr_thresh=5, plot=True, debug=False, verbose=False, save_plot=None, plot_title=None, angscale=False)

Detect blobs on the 2d array.

filter(method, mode, median_size=5, kernel_size=5, fwhm_size=5, btw_cutoff=0.2, btw_order=2, hann_cutoff=5, gauss_mode='conv')

High/low pass filtering the frames of the image.

Parameters:

• method ({'lp', 'hp'}) – Low-pass or high-pass filtering.

• mode (str) –

  Type of low/high-pass filtering. median

  [lp] applies a median low-pass filter to the image.

  gauss

  [lp] applies a Gaussian low-pass filter to the image.

  laplacian

  [hp] applies a Laplacian filter with kernel size defined by kernel_size using the Opencv library.

  laplacian-conv

  [hp] applies a Laplacian high-pass filter by defining a kernel (with kernel_size) and using the convolve_fft Astropy function.

  median-subt

  [hp] subtracts a median low-pass filtered version of the image.

  gauss-subt

  [hp] subtracts a Gaussian low-pass filtered version of the image.

  fourier-butter

  [hp] applies a high-pass 2D Butterworth filter in Fourier domain.

  hann

  [hp] uses a Hann window.

• median_size (int, optional) – Size of the median box for the median or median-subt filter.

• kernel_size (int, optional) – Size of the Laplacian kernel used in laplacian mode. It must be a positive odd integer value.

• fwhm_size (float, optional) – Size of the Gaussian kernel used in gauss or gauss-subt mode.

• btw_cutoff (float, optional) – Frequency cutoff for low-pass 2d Butterworth filter used in fourier-butter mode.

• btw_order (int, optional) – Order of low-pass 2d Butterworth filter used in fourier-butter mode.

• hann_cutoff (float) – Frequency cutoff for the hann mode.

• gauss_mode ({'conv', 'convfft'}, str optional) – ‘conv’ uses the multidimensional gaussian filter from scipy.ndimage and ‘convfft’ uses the fft convolution with a 2d Gaussian kernel.

get_center(verbose=True)

Get the coordinates of the center of the image.

Parameters:

verbose (bool optional) – If True the center coordinates are printed out.

plot(**kwargs)

Plot the 2d array.

Parameters:

**kwargs (dict, optional) – Parameters passed to the function plot_frames of the package HCIplot.

radial_profile(sep=1)

Calculate the average radial profile of an image.

Parameters:

sep (int, optional) – The average radial profile is recorded every sep pixels.

recenter(method='satspots', xy=None, subi_size=19, sigfactor=6, imlib='vip-fft', interpolation='lanczos4', debug=False, verbose=True)

Recenter the frame using the satellite spots or a radon transform.

Parameters:

• method ({'satspots', 'radon'}, str optional) – Method for recentering the frame.

• xy (tuple, optional) – Tuple with coordinates X,Y of the satellite spots. When the spots are in an X configuration, the order is the following: top-left, top-right, bottom-left and bottom-right. When the spots are in an + (cross-like) configuration, the order is the following: top, right, left, bottom.

rescale(scale, imlib='vip-fft', interpolation='bicubic', verbose=True)

Resample the image (upscaling or downscaling).

Parameters:

• scale (int, float or tuple) – Scale factor for upsampling or downsampling the frames in the cube. If a tuple it corresponds to the scale along x and y.

• imlib ({'ndimage', 'opencv', 'vip-fft'}, str optional) – Library used for image transformations. ndimage is the default.

• interpolation (str, optional) – For ‘ndimage’ library: ‘nearneig’, bilinear’, ‘bicuadratic’, ‘bicubic’, ‘biquartic’, ‘biquintic’. The ‘nearneig’ interpolation is the fastest and the ‘biquintic’ the slowest. The ‘nearneig’ is the worst option for interpolation of noisy astronomical images. For ‘opencv’ library: ‘nearneig’, ‘bilinear’, ‘bicubic’, ‘lanczos4’. The ‘nearneig’ interpolation is the fastest and the ‘lanczos4’ the slowest and accurate.

• verbose (bool, optional) – Whether to print out additional info such as the new image shape.

rotate(angle, imlib='vip-fft', interpolation='lanczos4', cxy=None)

Rotate the image by a given angle.

Parameters:

• imlib ({'opencv', 'skimage', 'vip-fft'}, str optional) – Library used for image transformations. Opencv is faster than ndimage or skimage.

• interpolation (str, optional) – For ‘skimage’ library: ‘nearneig’, bilinear’, ‘bicuadratic’, ‘bicubic’, ‘biquartic’, ‘biquintic’. The ‘nearneig’ interpolation is the fastest and the ‘biquintic’ the slowest. The ‘nearneig’ is the poorer option for interpolation of noisy astronomical images. For ‘opencv’ library: ‘nearneig’, ‘bilinear’, ‘bicubic’, ‘lanczos4’. The ‘nearneig’ interpolation is the fastest and the ‘lanczos4’ the slowest and accurate. ‘lanczos4’ is the default.

• cxy (tuple of int, optional) – Coordinates X,Y of the point with respect to which the rotation will be performed. By default the rotation is done with respect to the center of the frames, as it is returned by the function vip_hci.var.frame_center.

shift(shift_y, shift_x, imlib='vip-fft', interpolation='lanczos4')

Shift the image.

Parameters:

• shift_y (float) – Shifts in x and y directions.

• shift_x (float) – Shifts in x and y directions.

• imlib ({'opencv', 'ndimage-fourier', 'ndimage-interp', 'vip-fft'}, str opt) – Library or method used for performing the image shift. ‘ndimage-fourier’, does a fourier shift operation and preserves better the pixel values (therefore the flux and photometry). Interpolation based shift (‘opencv’ and ‘ndimage-interp’) is faster than the fourier shift. ‘opencv’ is recommended when speed is critical.

• interpolation ({'bicubic', 'bilinear', 'nearneig'}, optional) – Only used in case of imlib is set to ‘opencv’ or ‘ndimage-interp’, where the images are shifted via interpolation. For ‘ndimage-interp’ library: ‘nearneig’, bilinear’, ‘bicuadratic’, ‘bicubic’, ‘biquartic’, ‘biquintic’. The ‘nearneig’ interpolation is the fastest and the ‘biquintic’ the slowest. The ‘nearneig’ is the poorer option for interpolation of noisy astronomical images. For ‘opencv’ library: ‘nearneig’, ‘bilinear’, ‘bicubic’, ‘lanczos4’. The ‘nearneig’ interpolation is the fastest and the ‘lanczos4’ the slowest and accurate. ‘lanczos4’ is the default.

snr(source_xy, plot=False, verbose=True)

Calculate the S/N for a test resolution element source_xy.

Parameters:

• source_xy (tuple of floats) – X and Y coordinates of the planet or test speckle.

• plot (bool, optional) – Plots the frame and the apertures considered for clarity.

• verbose (bool, optional) – Chooses whether to print some output or not.

Returns:

snr_val – Value of the S/N for source_xy.

Return type:

float

stats(region='circle', radius=5, xy=None, annulus_inner_radius=0, annulus_width=5, source_xy=None, verbose=True, plot=True)

Calculate statistics on the image, both in the full-frame and in a region.

The region can be a circular aperture or an annulus. Also, the S/N of the either source_xy or the max pixel is calculated.

Parameters:

• region ({'circle', 'annulus'}, str optional) – Region in which basic statistics (mean, stddev, median and max) are calculated.

• radius (int, optional) – Radius of the circular aperture.

• xy (tuple of floats, optional) – Center of the circular aperture.

• annulus_inner_radius (int, optional) – Inner radius of the annular region.

• annulus_width (int, optional) – Width of the annular region.

• source_xy (tuple of floats, optional) – Coordinates for which the S/N information will be obtained. If None, the S/N is estimated for the pixel with the maximum value.

• verbose (bool, optional) – Whether to print out the values of the calculated statistics.

• plot (bool, optional) – Whether to plot the frame, histograms and region.

vip_hci.objects.postproc module

Module containing basic classes for manipulating post-processing algorithms.

This includes the core PostProc class, parent to every algorithm object implementation, but also the PPResult class, a container for the results obtained through those said algorithm objects. PPResult is provided with the Session dataclass, which defines the type of data stored from the results.

class vip_hci.objects.postproc.PPResult(load_from_path: str | None = None)

Bases: object

Container for results of post-processing algorithms.

For each given set of data and parameters, a frame is computed by the PostProc algorithms, as well as a S/N map associated. To keep track of each of them, this object remembers each set of parameters, frame and S/N map as a session. Sessions are numbered in order of creation from 0 to X, and they are displayed to the user as going from 1 to X+1.

fits_to_results(filepath: str, session_id: int = -2) → None

Load all configurations from a fits file.

Parameters:

filepath (str) – The path of the FITS file.

register_session(frame: ndarray, algo_name: str | None = None, params: dict | None = None, snr_map: ndarray | None = None) → None

Register data for a new session or updating data for an existing one.

Parameters:

• frame (np.ndarray) – Frame obtained after an iteration of a PostProc object.

• params (dictionnary, optional) – Set of parameters used for an iteration of a PostProc object.

• snr_map (np.ndarray, optional) – Signal-to-noise ratio map generated through the make_snrmap method of PostProc. Usually given after generating frame.

results_to_fits(filepath: str) → None

Save all configurations as a fits file.

Parameters:

filepath (str) – The path of the FITS file.

sessions: List

show_session_results(session_id: int | None = -1, label: Tuple[str] | bool | None = True) → None

Print the parameters and plot the frame (and S/N map if able) of a session(s).

Parameters:

session_id (int, list of int or str, optional) – The ID of the session(s) to show. It is possible to get several sessions results by giving a list of int or “all” to get all of them. By default, the last session is displayed (index -1).

class vip_hci.objects.postproc.PostProc(dataset: Dataset | None = None, verbose: bool = True, results: PPResult | None = None, frame_final: ndarray | None = None, signf: float | None = None)

Bases: BaseEstimator

Base post-processing algorithm class.

Does not need an __init__ because as a parent class for every algorithm object, there is no reason to create a PostProc object. Inherited classes benefit from the dataclass_builder support for their initialization and no further methods are needed to create those.

The PostProc is still very useful as it provides crucial utility common to all the inherited objects, such as :

• establishing a list of attributes which need to be calculated

• updating the dataset used for the algorithm if needed

• calculating the signal-to-noise ratio map after a corrected frame has been

generated - setting up parameters for the algorithm.

compute_significance(source_xy: Tuple[float] | None = None) → None

Compute the significance of a detection.

Parameters:

source_xy (Tuple of floats) – Coordinates of the detection.

dataset: Dataset = None

frame_final: ndarray = None

get_params_from_results(session_id: int) → None

Copy a previously registered configuration from the results to the object.

Parameters:

session_id (int) – The ID of the session to load the configuration from.

make_snrmap(approximated: bool | None = False, plot: bool | None = False, known_sources: Tuple | Tuple[Tuple] | None = None, nproc: int | None = None) → None

Calculate a S/N map from self.frame_final.

Parameters:

• results (PPResult object, optional) – Container for the results of the algorithm. May hold the parameters used, as well as the frame_final (and the snr_map if generated).

• approximated (bool, optional) – If True, a proxy to the S/N calculation will be used. If False, the Mawet et al. 2014 definition is used.

• plot (bool, optional) – If True plots the S/N map. True by default.

• known_sources (None, tuple or tuple of tuples, optional) – To take into account existing sources. It should be a tuple of float/int or a tuple of tuples (of float/int) with the coordinate(s) of the known sources.

• nproc (int or None) – Number of processes for parallel computing.

• verbose (bool, optional) – Whether to print timing or not.

Note

This is needed for “classic” algorithms that produce a final residual image in their .run() method. To obtain a “detection map”, which can be used for counting true/false positives, a SNR map has to be created. For other algorithms (like ANDROMEDA) which directly create a SNR or a probability map, this method should be overwritten and thus disabled.

print_parameters() → None

Print out the parameters of the algorithm.

results: PPResult = None

run() → None

Run the algorithm. Should at least set `` self.frame_final``.

Note

This is the required signature of the run call. Child classes can add their own keyword arguments if needed.

save(filename: str) → None

Pickle the algo object and save it to disk.

Note that this also saves the associated self.dataset, in a non-optimal way.

signf: float = None

verbose: bool = True

vip_hci.objects.ppandromeda module

Module for the post-processing ANDROMEDA algorithm.

vip_hci.objects.ppandromeda.AndroBuilder

alias of PPAndromedaBuilder

class vip_hci.objects.ppandromeda.PPAndromeda(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 = True, dataset: Dataset | None = None, results: PPResult | None = None, frame_final: ndarray | None = None, signf: float | None = None, _algo_name: str = 'andromeda', contrast_map: ndarray | None = None, likelihood_map: ndarray | None = None, snr_map: ndarray | None = None, snr_map_notnorm: ndarray | None = None, stdcontrast_map: ndarray | None = None, stdcontrast_map_notnorm: ndarray | None = None, ext_radius: int | None = None, detection_map: ndarray | None = None)

Bases: PostProc, ANDROMEDA_Params

Post-processing ANDROMEDA algorithm.

contrast_map: ndarray = None

detection_map: ndarray = None

ext_radius: int = None

likelihood_map: ndarray = None

run(dataset: Dataset | None = None, nproc: int | None = None)

Run the ANDROMEDA algorithm for model PSF subtraction.

Parameters:

• dataset (Dataset, optional) – Dataset to process. If not provided, self.dataset is used (as set when initializing this object).

• nproc (int, optional) – Number of processes to use.

• verbose (bool, optional) – Print some parameter values for control.

snr_map: ndarray = None

snr_map_notnorm: ndarray = None

stdcontrast_map: ndarray = None

stdcontrast_map_notnorm: ndarray = None

vip_hci.objects.ppfmmf module

Module for the post-processing FMMF algorithm.

vip_hci.objects.ppfmmf.FMMFBuilder

alias of PPFMMFBuilder

class vip_hci.objects.ppfmmf.PPFMMF(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, dataset: ~vip_hci.objects.dataset.Dataset | None = None, results: ~vip_hci.objects.postproc.PPResult | None = None, frame_final: ~numpy.ndarray | None = None, signf: float | None = None, _algo_name: str = 'fmmf', snr_map: ~numpy.ndarray | None = None)

Bases: PostProc, FMMF_Params

Post-processing forward model matching filter algorithm.

make_snrmap()

Do nothing, snr_map is already generated by fmmf.

This function must overload the inherited one to avoid misusage.

run(dataset: Dataset | None = None, nproc: int | None = None)

Run the post-processing FMMF algorithm for model PSF subtraction.

Parameters:

• dataset (Dataset object) – An Dataset object to be processed.

• model ({'KLIP', 'LOCI'}, optional) – If you want to change the default model. See documentation above for more information.

• nproc (None or int, optional) – Number of processes for parallel computing. If None the number of processes will be set to cpu_count()/2. By default the algorithm works in single-process mode.

• verbose (bool, optional) – If True prints to stdout intermediate info.

snr_map: ndarray = None

vip_hci.objects.ppframediff module

Module for the post-processing frame differencing algorithm.

vip_hci.objects.ppframediff.FrameDiffBuilder

alias of PPFrameDiffBuilder

class vip_hci.objects.ppframediff.PPFrameDiff(cube: ndarray | None = None, angle_list: ndarray | None = None, fwhm: float = 4, metric: Enum = Metric.MANHATTAN, dist_threshold: int = 50, n_similar: int | None = None, delta_rot: int = 0.5, radius_int: int = 2, asize: int = 4, ncomp: int | None = None, imlib: Enum = Imlib.VIPFFT, interpolation: Enum = Interpolation.LANCZOS4, collapse: Enum = Collapse.MEDIAN, nproc: int = 1, verbose: bool = True, debug: bool = False, full_output: bool = False, dataset: Dataset | None = None, results: PPResult | None = None, frame_final: ndarray | None = None, signf: float | None = None, _algo_name: str = 'frame_diff')

Bases: PostProc, FRAME_DIFF_Params

Post-processing frame differencing algorithm.

Parameters:

_algo_name (str, optional) – Name of the algorithm wrapped by the object.

run(dataset: Dataset | None = None, nproc: int | None = 1, full_output: bool | None = True, **rot_options: dict | None)

Run the post-processing median subtraction algorithm for model PSF subtraction.

Parameters:

• dataset (Dataset object) – A Dataset object to be processed.

• nproc (None or int, optional) – Number of processes for parallel computing. If None the number of processes will be set to cpu_count()/2. By default the algorithm works in single-process mode.

• full_output (bool, optional) – Whether to return the final median combined image only or with other intermediate arrays.

• rot_options (dictionary, optional) – Dictionary with optional keyword values for “border_mode”, “mask_val”, “edge_blend”, “interp_zeros”, “ker” (see documentation of vip_hci.preproc.frame_rotate).

vip_hci.objects.ppllsg module

Module for the post-processing LLSG algorithm.

vip_hci.objects.ppllsg.LLSGBuilder

alias of PPLLSGBuilder

class vip_hci.objects.ppllsg.PPLLSG(cube: ndarray | None = None, angle_list: ndarray | None = None, fwhm: float | None = None, rank: int = 10, thresh: float = 1, max_iter: int = 10, low_rank_ref: bool = False, low_rank_mode: Enum = LowRankMode.SVD, auto_rank_mode: Enum = AutoRankMode.NOISE, residuals_tol: float = 0.1, cevr: float = 0.9, thresh_mode: Enum = ThreshMode.SOFT, nproc: int = 1, asize: int | None = None, n_segments: int = 4, azimuth_overlap: int | None = None, radius_int: int | None = None, random_seed: int | None = None, high_pass: int | None = None, collapse: Enum = Collapse.MEDIAN, full_output: bool = True, verbose: bool = True, debug: bool = False, dataset: Dataset | None = None, results: PPResult | None = None, frame_final: ndarray | None = None, signf: float | None = None, _algo_name: str = 'llsg', frame_l: ndarray | None = None, frame_s: ndarray | None = None, frame_g: ndarray | None = None)

Bases: PostProc, LLSG_Params

Post-processing LLSG algorithm.

Parameters:

• full_output (bool, optional) – Whether to return the final median combined image only or with other intermediate arrays.

• _algo_name (str, optional) – Name of the algorithm wrapped by the object.

frame_g: ndarray = None

frame_l: ndarray = None

frame_s: ndarray = None

full_output: bool = True

run(dataset: Dataset | None = None, nproc: int | None = None, full_output: bool | None = True, **rot_options: dict | None)

Run the post-processing LLSG algorithm for model PSF subtraction.

Parameters:

• dataset (Dataset, optional) – Dataset to process. If not provided, self.dataset is used (as set when initializing this object).

• nproc (int, optional)

• full_output (boolean, optional) – Whether to return the final median combined image only or with other intermediate arrays.

• rot_options (dictionary, optional) – Dictionary with optional keyword values for “border_mode”, “mask_val”, “edge_blend”, “interp_zeros”, “ker” (see documentation of vip_hci.preproc.frame_rotate)

vip_hci.objects.pploci module

Module for the post-processing LOCI algorithm.

vip_hci.objects.pploci.LOCIBuilder

alias of PPLOCIBuilder

class vip_hci.objects.pploci.PPLOCI(cube: ndarray | None = None, angle_list: ndarray | None = None, scale_list: ndarray | None = None, fwhm: float = 4, metric: Enum = Metric.MANHATTAN, dist_threshold: int = 100, delta_rot: float | Tuple[float] = (0.1, 1), delta_sep: float | Tuple[float] = (0.1, 1), radius_int: int = 0, asize: int = 4, n_segments: int = 4, nproc: int = 1, solver: Enum = Solver.LSTSQ, tol: float = 0.01, optim_scale_fact: float = 2, adimsdi: Enum = Adimsdi.SKIPADI, imlib: Enum = Imlib.VIPFFT, interpolation: Enum = Interpolation.LANCZOS4, collapse: Enum = Collapse.MEDIAN, verbose: bool = True, full_output: bool = True, dataset: Dataset | None = None, results: PPResult | None = None, frame_final: ndarray | None = None, signf: float | None = None, _algo_name: str = 'xloci', cube_res: ndarray | None = None, cube_der: ndarray | None = None)

Bases: PostProc, XLOCI_Params

Post-processing LOCI algorithm.

Parameters:

• full_output (bool, optional) – Whether to return the final median combined image only or with other intermediate arrays.

• _algo_name (str, optional) – Name of the algorithm wrapped by the object.

cube_der: ndarray = None

cube_res: ndarray = None

full_output: bool = True

run(dataset: Dataset | None = None, nproc: int | None = None, **rot_options: dict | None)

Run the post-processing LOCI algorithm for model PSF subtraction.

Parameters:

• dataset (Dataset, optional) – Dataset to process. If not provided, self.dataset is used (as set when initializing this object).

• nproc (int, optional)

• verbose (bool, optional) – If True prints to stdout intermediate info.

• full_output (boolean, optional) – Whether to return the final median combined image only or with other intermediate arrays.

• rot_options (dictionary, optional) – Dictionary with optional keyword values for “border_mode”, “mask_val”, “edge_blend”, “interp_zeros”, “ker” (see documentation of vip_hci.preproc.frame_rotate)

vip_hci.objects.ppmediansub module

Module for the post-processing median subtraction algorithm.

vip_hci.objects.ppmediansub.MedianBuilder

alias of PPMedianSubBuilder

class vip_hci.objects.ppmediansub.PPMedianSub(cube: ndarray | None = None, angle_list: ndarray | None = None, scale_list: ndarray | None = None, flux_sc_list: ndarray | None = None, fwhm: float = 4, radius_int: int = 0, asize: int = 4, delta_rot: int = 1, delta_sep: float | Tuple[float] = (0.1, 1), mode: str = 'fullfr', nframes: int = 4, sdi_only: bool = False, imlib: Enum = Imlib.VIPFFT, interpolation: Enum = Interpolation.LANCZOS4, collapse: Enum = Collapse.MEDIAN, nproc: int = 1, full_output: bool = True, verbose: bool = True, dataset: Dataset | None = None, results: PPResult | None = None, frame_final: ndarray | None = None, signf: float | None = None, _algo_name: str = 'median_sub', cube_residuals: ndarray | None = None, cube_residuals_der: ndarray | None = None)

Bases: PostProc, MEDIAN_SUB_Params

Object used as a wrapper for the vip_hci.psfsub.median_sub.

Gets its parameters from the MedsubParams dataclass.

Parameters:

• full_output (bool, optional) – Whether to return the final median combined image only or with other intermediate arrays.

• _algo_name (str, optional) – Name of the algorithm wrapped by the object.

cube_residuals: ndarray = None

cube_residuals_der: ndarray = None

full_output: bool = True

run(dataset: Dataset | None = None, nproc: int | None = None, full_output: bool | None = None, **rot_options: dict | None) → None

Run the post-processing median subtraction algorithm for model PSF subtraction.

Parameters:

• results (PPResult object, optional) – Container for the results of the algorithm. May hold the parameters used, as well as the frame_final (and the snr_map if generated).

• dataset (Dataset object, optional) – An Dataset object to be processed.

• nproc (None or int, optional) – Number of processes for parallel computing. If None the number of processes will be set to cpu_count()/2. By default the algorithm works in single-process mode.

• full_output (bool, optional) – Whether to return the final median combined image only or with other intermediate arrays.

• verbose (bool, optional) – If True prints to stdout intermediate info.

• rot_options (dictionary, optional) – Dictionary with optional keyword values for “border_mode”, “mask_val”, “edge_blend”, “interp_zeros”, “ker” (see documentation of vip_hci.preproc.frame_rotate).

vip_hci.objects.ppnmf module

Module for the post-processing non-negative matrix factorization algorithm.

vip_hci.objects.ppnmf.NMFBuilder

alias of PPNMFBuilder

class vip_hci.objects.ppnmf.PPNMF(cube: ~numpy.ndarray | None = None, angle_list: ~numpy.ndarray | None = None, cube_ref: ~numpy.ndarray | None = None, ncomp: int = 1, scaling: ~enum.Enum | None = None, max_iter: int = 1000, random_state: int | None = None, mask_center_px: int | None = None, source_xy: ~typing.Tuple[int] | None = None, delta_rot: int | float | ~typing.Tuple[float] = (0.1, 1), fwhm: float = 4, init_svd: ~enum.Enum = Initsvd.NNDSVD, collapse: ~enum.Enum = Collapse.MEDIAN, full_output: bool = True, verbose: bool = True, cube_sig: ~numpy.ndarray | None = None, handle_neg: ~enum.Enum = HandleNeg.MASK, nmf_args: dict = <factory>, radius_int: int = 0, asize: int = 4, n_segments: int = 1, nproc: int = 1, min_frames_lib: int = 2, max_frames_lib: int = 200, imlib: ~enum.Enum = Imlib.VIPFFT, interpolation: ~enum.Enum = Interpolation.LANCZOS4, theta_init: float = 0, weights: ~typing.List | None = None, dataset: ~vip_hci.objects.dataset.Dataset | None = None, results: ~vip_hci.objects.postproc.PPResult | None = None, frame_final: ~numpy.ndarray | None = None, signf: float | None = None, _algo_name: ~typing.List[str] = <factory>, nmf_reshaped: ~numpy.ndarray | None = None, cube_residuals: ~numpy.ndarray | None = None, cube_residuals_der: ~numpy.ndarray | None = None, cube_residuals_resc: ~numpy.ndarray | None = None)

Bases: PostProc, NMF_ANNULAR_Params, NMF_Params

Post-processing full-frame non-negative matrix factorization algorithm.

Parameters:

• delta_rot (int or float or tuple of floats, optional) – Factor for tunning the parallactic angle threshold, expressed in FWHM. Due to this parameter being shared between annular and fullframe versions of NMF, the annular version is forcefully set by default. If the fullframe version is selected, the default value is changed to the fullframe value.

• full_output (bool, optional) – Whether to return the final median combined image only or with other intermediate arrays.

• _algo_name (str, optional) – Name of the algorithm wrapped by the object.

cube_residuals: ndarray = None

cube_residuals_der: ndarray = None

cube_residuals_resc: ndarray = None

delta_rot: int | float | Tuple[float] = (0.1, 1)

full_output: bool = True

nmf_reshaped: ndarray = None

run(runmode: str | None = 'fullframe', dataset: Dataset | None = None, nproc: int | None = 1, verbose: bool | None = None, **rot_options: dict | None)

Run the post-processing NMF algorithm for model PSF subtraction.

Parameters:

• runmode ({'fullframe', 'annular'}) – Defines which version of NMF to run between full frame and annular.

• dataset (Dataset object) – An Dataset object to be processed.

• nproc (None or int, optional) – Number of processes for parallel computing. If None the number of processes will be set to cpu_count()/2.

• full_output (bool, optional) – Whether to return the final median combined image only or with other intermediate arrays.

• verbose (bool, optional) – If True prints to stdout intermediate info.

• rot_options (dictionary, optional) – Dictionary with optional keyword values for “border_mode”, “mask_val”, “edge_blend”, “interp_zeros”, “ker” (see documentation of vip_hci.preproc.frame_rotate).

vip_hci.objects.pppca module

Module for the post-processing PCA algorithm.

vip_hci.objects.pppca.PCABuilder

alias of PPPCABuilder

class vip_hci.objects.pppca.PPPCA(cube: ~numpy.ndarray = None, angle_list: ~numpy.ndarray = None, cube_ref: ~numpy.ndarray = None, scale_list: ~numpy.ndarray = None, radius_int: int = 0, fwhm: float = 4, asize: float = 4, n_segments: int | ~typing.List[int] | auto = 1, delta_rot: int = None, delta_sep: float | ~typing.Tuple[float] = (0.1, 1), ncomp: ~typing.Tuple | ~typing.List | float | int = 1, svd_mode: ~enum.Enum = SvdMode.LAPACK, nproc: int = 1, min_frames_lib: int = 2, max_frames_lib: int = 200, tol: float = 0.1, scaling: ~enum.Enum = None, imlib: ~enum.Enum = Imlib.VIPFFT, interpolation: ~enum.Enum = Interpolation.LANCZOS4, collapse: ~enum.Enum = Collapse.MEDIAN, collapse_ifs: ~enum.Enum = Collapse.MEAN, ifs_collapse_range: str | ~typing.Tuple[int] = 'all', theta_init: int = 0, weights: ~numpy.ndarray = None, cube_sig: ~numpy.ndarray = None, full_output: bool = False, verbose: bool = True, left_eigv: bool = False, mask_center_px: int = None, source_xy: ~typing.Tuple[int] = None, adimsdi: ~enum.Enum = Adimsdi.SINGLE, crop_ifs: bool = True, imlib2: ~enum.Enum = Imlib.VIPFFT, mask_rdi: ~numpy.ndarray = None, check_memory: bool = True, batch: int | float = None, min_frames_pca: int = 10, dataset: ~vip_hci.objects.dataset.Dataset = None, results: ~vip_hci.objects.postproc.PPResult = None, frame_final: ~numpy.ndarray = None, signf: float = None, _algo_name: ~typing.List[str] = <factory>, cube_residuals: ~numpy.ndarray = None, cube_residuals_der: ~numpy.ndarray = None, pcs: ~numpy.ndarray = None, cube_residuals_per_channel: ~numpy.ndarray = None, cube_residuals_per_channel_der: ~numpy.ndarray = None, cube_residuals_resc: ~numpy.ndarray = None, final_residuals_cube: ~numpy.ndarray = None, medians: ~numpy.ndarray = None, frames_final: ~numpy.ndarray = None, range_pcs: ~typing.Tuple[int] = None, mode: str = 'fullfr', fmerit: str = 'mean', plot: bool = True, save_plot: str = None, exclude_negative_lobes: bool = False, initial_4dshape: ~typing.Tuple = None, dataframe: ~pandas.core.frame.DataFrame = None, pc_list: ~typing.List = None, opt_number_pc: int = None, annulus_width: float = None, r_guess: float = None)

Bases: PostProc, PCA_Params, PCA_ANNULAR_Params

Post-processing PCA algorithm, compatible with various options.

Depending on what mode you need, parameters may vary. Check the list below to ensure which arguments are required. Currently, four variations of the PCA can be called :

• full-frame PCA

• annular PCA

• grid PCA

• single annulus PCA.

Some parameters are common to several variations.

Common parameters

full_output: bool, optional

Whether to return the final median combined image only or with other intermediate arrays.

_algo_name: str, optional

Name of the algorithm wrapped by the object.

Grid parameters

range_pcsNone or tuple, optional

The interval of PCs to be tried. Refer to vip_hci.psfsub.pca_grid for more information.

mode{‘fullfr’, ‘annular’}, optional

Mode for PCA processing (full-frame or just in an annulus).

fmerit{‘px’, ‘max’, ‘mean’}

The function of merit to be maximized. ‘px’ is source_xy pixel’s SNR, ‘max’ the maximum SNR in a FWHM circular aperture centered on source_xy and ‘mean’ is the mean SNR in the same circular aperture.

plotbool, optional

Whether to plot the SNR and flux as functions of PCs and final PCA frame or not.

save_plot: string

If provided, the pc optimization plot will be saved to that path.

initial_4dshapeNone or tuple, optional

Shape of the initial ADI+mSDI cube.

exclude_negative_lobesbool, opt

Whether to include the adjacent aperture lobes to the tested location or not. Can be set to True if the image shows significant neg lobes.

Single annulus parameters

r_guessfloat

Radius of the annulus in pixels.

annulus_width: float = None

cube_residuals: ndarray = None

cube_residuals_der: ndarray = None

cube_residuals_per_channel: ndarray = None

cube_residuals_per_channel_der: ndarray = None

cube_residuals_resc: ndarray = None

cube_sig: ndarray = None

dataframe: DataFrame = None

exclude_negative_lobes: bool = False

final_residuals_cube: ndarray = None

fmerit: str = 'mean'

frames_final: ndarray = None

full_output: bool = True

initial_4dshape: Tuple = None

medians: ndarray = None

mode: str = 'fullfr'

opt_number_pc: int = None

pc_list: List = None

pcs: ndarray = None

plot: bool = True

r_guess: float = None

range_pcs: Tuple[int] = None

run(runmode: str | None = Runmode.CLASSIC, dataset: Dataset | None = None, nproc: int | None = 1, verbose: bool | None = True, full_output: bool | None = True, **rot_options: dict | None)

Run the post-processing PCA algorithm for model PSF subtraction.

Depending on the desired mode - full-frame or annular - parameters used will diverge, and calculated attributes may vary as well. In full-frame case :

3D case:

cube_reconstructed cube_residuals cube_residuals_der

3D case, source_xy is None:

cube_residuals pcs

4D case, adimsdi=”double”:

cube_residuals_per_channel cube_residuals_per_channel_der

4D case, adimsdi=”single”:

cube_residuals cube_residuals_resc

Parameters:

• runmode (Enum, see vip_hci.config.paramenum.Runmode) – Mode of execution for the PCA.

• dataset (Dataset, optional) – Dataset to process. If not provided, self.dataset is used (as set when initializing this object).

• nproc (int, optional)

• verbose (bool, optional) – If True prints to stdout intermediate info.

• full_output (boolean, optional) – Whether to return the final median combined image only or with other intermediate arrays.

• rot_options (dictionary, optional) – Dictionary with optional keyword values for “border_mode”, “mask_val”, “edge_blend”, “interp_zeros”, “ker” (see documentation of vip_hci.preproc.frame_rotate)

save_plot: str = None

Module contents

Subpackage objects containing a large number object-oriented modules.

They are implementing PSF subtraction and inverse problem approach algorithms found in vip_hci.psfsub and vip_hci.invprob. The modules included are the following : - median subtraction. - frame differencing. - LOCI. - PCA. - full-frame and annular versions of NMF. - LLSG. - ANDROMEDA. - FMMF.