vip_hci.config package

Submodules

vip_hci.config.mem module

System memory related functions

vip_hci.config.mem.check_enough_memory(input_bytes, factor=1, raise_error=True, error_msg='', verbose=True)

Check if input_bytes are larger than system’s available memory times factor. This function is used to check the inputs (largest ones such as multi-dimensional cubes) of algorithms and avoid system/Python crashes or heavy swapping.

Parameters:

• input_bytes (float) – The size in bytes of the inputs of a given function.

• factor (float, optional) – Scales how much memory is needed in terms of the size of input_bytes.

• raise_error (bool, optional) – If True, a RuntimeError is raised when the condition is not met.

• error_msg (str, optional) – [raise_error=True] To be appended to the message of the RuntimeError.

• verbose (bool, optional) – If True, information about the available memory is printed out.

vip_hci.config.mem.get_available_memory(verbose=True)

Get the available memory in bytes.

Parameters:

verbose (bool, optional) – Print out the total/available memory

Returns:

available_memory – The available memory in bytes.

Return type:

int

vip_hci.config.param module

Dictionaries with telescope/instrument parameters.

Usage

from vip_hci.config import VLT_NACO
lbda = VLT_NACO['lambdal']
diameter = VLT_NACO['diam']
pxscale = VLT_NACO['plsc']

resel = lambda/diameter*206265/pxscale

vip_hci.config.paramenum module

Module containing enums for parameters of HCI algorithms and literal constants.

class vip_hci.config.paramenum.Adimsdi(value)

Bases: str, Enum

Define modes for processing ADI+mSDI cubes through PCA.

Modes

• SINGLE: PCA only. The multi-spectral frames are rescaled wrt the largest

wavelength to align the speckles and all the frames (n_channels * n_adiframes) are processed with a single PCA low-rank approximation.

• DOUBLE: PCA and LOCI. A first stage is run on the rescaled spectral frames,

and a second frame is run on the residuals in an ADI fashion.

• SKIPADI: LOCI only. The multi-spectral frames are rescaled wrt the largest

wavelength to align the speckles and the least-squares model is subtracted on each spectral cube separately.

DOUBLE = 'double'

SINGLE = 'single'

SKIPADI = 'skipadi'

class vip_hci.config.paramenum.AutoRankMode(value)

Bases: str, Enum

Define the values for the auto rank mode for LLSG.

CEVR = 'cevr'

NOISE = 'noise'

class vip_hci.config.paramenum.Collapse(value)

Bases: str, Enum

Define modes for spectral/temporal residuals frames combining.

Modes

• ̀``MEDIAN``

• ̀``MEAN``

• ̀``SUM``

• ̀``TRIMMEAN``

MEAN = 'mean'

MEDIAN = 'median'

SUM = 'sum'

TRIMMEAN = 'trimmean'

class vip_hci.config.paramenum.HandleNeg(value)

Bases: str, Enum

Define modes for handling negative values in NMF full-frame.

Modes

• SUBTR_MIN : subtract the minimum value in the arrays.

• MASK : mask negative values.

• NULL : set negative values to zero.

MASK = 'mask'

NULL = 'null'

SUBTR_MIN = 'subtr_min'

class vip_hci.config.paramenum.Imlib(value)

Bases: str, Enum

Define modes for image transformations to be used.

Modes

• ̀``OPENCV``: uses OpenCV. Faster than Skimage or scipy.ndimage.

• ̀``SKIMAGE``: uses Skimage.

• NDIMAGE: uses scipy.ndimage.

• ̀``VIPFFT``: uses VIP FFT based rotation method.

NDIMAGE = 'ndimage'

OPENCV = 'opencv'

SKIMAGE = 'skimage'

VIPFFT = 'vip-fft'

class vip_hci.config.paramenum.Initsvd(value)

Bases: str, Enum

Define modes for initializing SVD for NMF full-frame.

Modes

• NNDSVD: non-negative double SVD recommended for sparseness.

• NNDSVDANNDSVD where zeros are filled with the average of cube;

  recommended when sparsity is not desired.

• RANDOM : random initial non-negative matrix.

NNDSVD = 'nndsvd'

NNDSVDA = 'nndsvda'

RANDOM = 'random'

class vip_hci.config.paramenum.Interpolation(value)

Bases: str, Enum

Define modes for interpolation.

Modes

• ̀``NEARNEIG``

• ̀``BILINEAR``

• ̀``BIQUADRATIC`` : Default for Skimage (only).

• ̀``BICUBIC``

• ̀``BIQUARTIC`` : Skimage only.

• ̀``BIQUINTIC`` : slowest and most accurate. Skimage only.

• ̀``LANCZOS4`` : slowest and most accurate. Default for OpenCV.

BICUBIC = 'bicubic'

BILINEAR = 'bilinear'

BIQUADRATIC = 'biquadratic'

BIQUARTIC = 'biquartic'

BIQUINTIC = 'biquintic'

LANCZOS4 = 'lanczos4'

NEARNEIG = 'nearneig'

class vip_hci.config.paramenum.LowRankMode(value)

Bases: str, Enum

Define the values for the low rank mode for LLSG.

BRP = 'brp'

SVD = 'svd'

class vip_hci.config.paramenum.Metric(value)

Bases: str, Enum

Define all metrics possible for various post-processing functions.

CITYBLOCK = 'cityblock'

CORRELATION = 'correlation'

COSINE = 'cosine'

EUCLIDEAN = 'euclidean'

L1 = 'l1'

L2 = 'l2'

MANHATTAN = 'manhattan'

class vip_hci.config.paramenum.OptMethod(value)

Bases: str, Enum

Defines the method of balancing for the flux difference for ANDROMEDA.

Modes

• NO

• TOTAL

• LSQ

• ROBUST

LSQ = 'lsq'

NO = 'no'

ROBUST = 'robust'

TOTAL = 'total'

class vip_hci.config.paramenum.ReturnList(value)

Bases: str, Enum

List of all possible modes of classic PCA.

ADIMSDI_DOUBLE = 'adimsdi_double'

ADIMSDI_SINGLE_GRID_NO_SOURCE = 'adimsdi_single_grid_no_source'

ADIMSDI_SINGLE_GRID_SOURCE = 'adimsdi_single_grid_source'

ADIMSDI_SINGLE_NO_GRID = 'adimsdi_single_no_grid'

ADI_FULLFRAME_GRID = 'adi_fullframe_grid'

ADI_FULLFRAME_STANDARD = 'adi_fullframe_standard'

ADI_INCREMENTAL_BATCH = 'adi_incremental_batch'

PCA_GRID_SN = 'pca_grid_sn'

PCA_ROT_THRESH = 'pca_rot_thresh'

class vip_hci.config.paramenum.Runmode(value)

Bases: str, Enum

Define the mode for the PostProc PCA object.

Modes

• CLASSIC : base PCA function, with multiple usages depending on the

parameters given.

• ANNULAR : annular PCA function.

• GRID : grid PCA function (can be used implicitely from “classic”).

• ANNULUS : annulus PCA function.

ANNULAR = 'annular'

ANNULUS = 'annulus'

CLASSIC = 'classic'

GRID = 'grid'

class vip_hci.config.paramenum.Scaling(value)

Bases: str, Enum

Define modes for the pixel-wise scaling.

Modes

• TEMPMEAN: temporal px-wise mean is subtracted.

• SPATMEAN: spatial mean is subtracted.

• TEMPSTANDARD: temporal mean centering plus scaling pixel values

to unit variance. HIGHLY RECOMMENDED FOR ASDI AND RDI CASES!

• SPATSTANDARD: spatial mean centering plus scaling pixel values

to unit variance.

SPATMEAN = 'spat-mean'

SPATSTANDARD = 'spat-standard'

TEMPMEAN = 'temp-mean'

TEMPSTANDARD = 'temp-standard'

class vip_hci.config.paramenum.Solver(value)

Bases: str, Enum

Define the solver for the least squares problem in LLSG.

Modes

• LSTSQ : uses the standard scipy least squares solver.

• NNLS : uses the scipy non-negative least-squares solver.

LSTSQ = 'lstsq'

NNLS = 'nnls'

class vip_hci.config.paramenum.SvdMode(value)

Bases: str, Enum

Define the various modes to use with SVD in PCA as constant strings.

Modes

• LAPACK: uses the LAPACK linear algebra library through Numpy

and it is the most conventional way of computing the SVD (deterministic result computed on CPU).

• ARPACK: uses the ARPACK Fortran libraries accessible through

Scipy (computation on CPU).

• EIGEN: computes the singular vectors through the

eigendecomposition of the covariance M.M’ (computation on CPU).

• RANDSVD: uses the randomized_svd algorithm implemented in

Sklearn (computation on CPU), proposed in [HAL09].

• CUPY: uses the Cupy library for GPU computation of the SVD as in

the LAPACK version. `

• EIGENCUPY: offers the same method as with the eigen option

but on GPU (through Cupy).

• RANDCUPY: is an adaptation of the randomized_svd algorithm,

where all the computations are done on a GPU (through Cupy). `

• PYTORCH: uses the Pytorch library for GPU computation of the SVD.

• EIGENPYTORCH: offers the same method as with the eigen

option but on GPU (through Pytorch).

• RANDPYTORCH: is an adaptation of the randomized_svd algorithm,

where all the linear algebra computations are done on a GPU (through Pytorch).

ARPACK = 'arpack'

CUPY = 'cupy'

EIGEN = 'eigen'

EIGENCUPY = 'eigencupy'

EIGENPYTORCH = 'eigenpytorch'

LAPACK = 'lapack'

PYTORCH = 'pytorch'

RANDCUPY = 'randcupy'

RANDPYTORCH = 'randpytorch'

RANDSVD = 'randsvd'

class vip_hci.config.paramenum.ThreshMode(value)

Bases: str, Enum

Define the values for thresholding modes for LLSG.

HARD = 'hard'

SOFT = 'soft'

class vip_hci.config.paramenum.VarEstim(value)

Bases: str, Enum

Define modes to use for the residual noise variance estimation in FMMF.

Modes

• FR: consider the pixels in the selected annulus with a width equal

to asize but separately for every frame.

• FM: consider the pixels in the selected annulus with a width

equal to asize but separately for every frame. Apply a mask one FWHM on the selected pixel and its surrounding.

• TE:rely on the method developped in PACO to estimate the

residual noise variance (take the pixels in a region of one FWHM arround the selected pixel, considering every frame in the derotated cube of residuals except for the selected frame).

FM = 'fm'

FR = 'fr'

TE = 'te'

vip_hci.config.timing module

Functions for timing other functions/procedures.

vip_hci.config.timing.time_fin(start_time)

Return the execution time of a script.

It requires the initialization with the function time_ini().

vip_hci.config.timing.time_ini(verbose=True)

Set and print the time at which the script started.

Returns:

start_time – Starting time.

Return type:

string

vip_hci.config.timing.timing(start_time)

Print the execution time of a script.

It requires the initialization with the function time_ini().

vip_hci.config.utils_conf module

Module with utilities.

class vip_hci.config.utils_conf.Progressbar(iterable=None, desc=None, total=None, leave=True, backend=None, verbose=True)

Bases: object

Show progress bars. Supports multiple backends.

Examples

from vip_hci.var import Progressbar
Progressbar.backend = "tqdm"

from time import sleep

for i in Progressbar(range(50)):
    sleep(0.02)

# or:

bar = Progressbar(total=50):
for i in range(50):
    sleep(0.02)
    bar.update()

# Progressbar can be disabled globally using
Progressbar.backend = "hide"

# or locally using the ``verbose`` keyword:
Progressbar(iterable, verbose=False)

backend = 'pyprind'

set()

vip_hci.config.utils_conf.check_array(input_array, dim, msg=None)

Checks the dimensionality of input. In case the check is not successful, a TypeError is raised.

Parameters:

• input_array (list, tuple or np.ndarray) – Input data.

• dim (int or tuple) – Number of dimensions that input_array should have. dim can take one of these values: 1, 2, 3, 4, (1,2), (2,3), (3,4) or (2,3,4).

• msg (str, optional) – String to be used in the error message (input_array name).

vip_hci.config.utils_param module

Module for various object oriented functions.

vip_hci.config.utils_param.filter_duplicate_keys(filter_item: any, ref_item: any, filter_in: bool = True)

Filter in or out keys of an item based on a reference item.

Can keep only the keys from a reference item or exclude all of them, based on the boolean filter_in.

Parameters:

• filter_item (Object or dict) – An object or a dictionnary that needs to be filtered.

• ref_item (Object or dict) – An object or a dictionnary that gives the keys wanted for filtering.

• filter_in (bool) – If True, keeps only the keys from reference, else erase only those keys.

vip_hci.config.utils_param.print_algo_params(function_parameters: dict) → None

Print the parameters that will be used for the run of an algorithm.

vip_hci.config.utils_param.separate_kwargs_dict(initial_kwargs: dict, parent_class: any) → None

Take a set of kwargs parameters and split them in two separate dicts.

The condition for the separation is to extract the parameters of an object (example: PCA_Params) and leave the other parameters as another dictionnary. This is used in vip_hci.psfsub and vip_hci.invprob functions to allow both the parameters of the function and the usual rot_options to be passed as one kwargs.

Parameters:

• initial_kwargs (dict) – The complete set of kwargs to separate.

• parent_class (class) – The model containing the parameters to extract into the first dictionnary.

Returns:

• class_params (dict) – Parameters for the parent class to initialize.

• more_params (dict) – Parameters left after extracting the class_params.

vip_hci.config.utils_param.setup_parameters(params_obj: object, fkt: Callable, as_list: bool = False, show_params: bool = False, **add_params: dict) → any

Help creating a dictionnary of parameters for a given function.

Look for the exact list of parameters needed for the fkt function and takes only the attributes needed from the params_obj. More parameters can be included with the **add_pararms dictionnary.

Parameters:

• params_obj (object) – Parameters to sort and order for the function.

• fkt (function) – The function we want to give parameters to.

• as_list (boolean) – Determines if the set of parameters should be return as a list instead of a dictionnary.

• **add_params (dictionnary, optional) – Additionnal parameters that may not be included in the params_obj.

Returns:

params_setup – The dictionnary comprised of parameters needed for the function, selected amongst attributes of PostProc objects and additionnal parameters. Can be a list if asked for (used in specific cases such as when calling functions through vip_hci.config.utils_conf.pool_map, see an example in vip_hci.psfsub.framediff).

Return type:

dictionnary or list

Module contents

Subpackage conf contains configuration functions and internal utilities. It also contains a dictionary with parameters of high-contrast imaging instruments.