draco.util.tools

Collection of miscellaneous routines.

Miscellaneous tasks should be placed in draco.core.misc.

Functions

apply_gain(vis, gain[, axis, out, prod_map])	Apply per input gains to a set of visibilities packed in upper triangular format.
arPLS_1d(y[, mask, lam, end_frac, max_iter])	Use arPLS to estimate a signal baseline.
baseline_vector(index_map, telescope)	Baseline vectors in meters.
calculate_redundancy(input_flags, prod_map, ...)	Calculates the number of redundant baselines that were stacked to form each unique baseline.
cmap(i, j, n)	Given a pair of feed indices, return the pair index.
correct_phase_wrap(phi[, deg])	Correct for phase wrapping.
extract_diagonal(utmat[, axis])	Extract the diagonal elements of an upper triangular array.
find_contiguous_slices(index)	Convert indices into a list of slices.
find_inputs(input_index, inputs[, require_match])	Find the indices of inputs into a list of inputs.
find_key(key_list, key)	Find the index of a key in a list of keys.
find_keys(key_list, keys[, require_match])	Find the indices of keys into a list of keys.
icmap(ix, n)	Inverse feed map.
polarization_map(index_map, telescope[, ...])	Map the visibilities corresponding to entries in pol = ['XX', 'XY', 'YX', 'YY'].
redefine_stack_index_map(telescope, inputs, ...)	Ensure baselines between unmasked inputs are used to represent each stack.
taper_mask(mask, nwidth[, outer])	Taper a 2d mask along the last axis.
window_generalised(x[, window])	A generalised high-order window at arbitrary locations.

draco.util.tools.apply_gain(vis, gain, axis=1, out=None, prod_map=None)

Apply per input gains to a set of visibilities packed in upper triangular format.

This allows us to apply the gains while minimising the intermediate products created.

Parameters:

• vis (np.ndarray[..., nprod, ...]) – Array of visibility products.

• gain (np.ndarray[..., ninput, ...]) – Array of gains. One gain per input.

• axis (integer, optional) – The axis along which the inputs (or visibilities) are contained.

• out (np.ndarray) – Array to place output in. If None create a new array. This routine can safely use out = vis.

• prod_map (ndarray of integer pairs) – Gives the mapping from product axis to input pairs. If not supplied, icmap() is used.

Returns:

out – Visibility array with gains applied. Same shape as vis.

Return type:

np.ndarray

draco.util.tools.arPLS_1d(y, mask=None, lam=100.0, end_frac=0.01, max_iter=1000)

Use arPLS to estimate a signal baseline.

1D implementation of symmetrically reweighted penalized least squares. Solves for a signal baseline in the presence of high power outliers by heavily weighting values below the signal and minimizing the weights of values above the signal.

Notes

arPLS solves the following linear system given signal :math: mathtt{y} .. math:: (W + lambdaD_{d}^{T}D_{d})z = Wy where the weighting function is given by .. math:: w_{i} = (1 + exp(2sigma^{-1}(r_{i} - (2sigma - mu))))^{-1} where \(\mathtt{r_{i}}\) is the difference \(\mathtt{y_{i} - z_{i}}\) and \(\mathtt{\mu}\) and \(\mathtt{\sigma}\) are the mean and standard deviation of the negative values in \(\mathbf{r}\). The solver runs until max_iter iterations, or until the fractional mean change in weights is less than end_frac.

Reference: https://www.sciencedirect.com/science/article/pii/S1090780706002266

Properties

ynp.ndarray

1D signal array

masknp.ndarray, optional

1D boolean array of same length as y. Default is None.

lamfloat, optional

Scaling parameter used to control importance of smoothness vs. fit. High value prioritizes smoothness of the baseline estimate. Default is 1e2.

end_fracfloat, optional

Convergeance ratio norm(delta_w) / norm(w).

max_iterint, optional

Maximum number of iterations to run, even if the convergance criteria is not met.

returns:

z – Baseline estimate of the same shape as y

rtype:

np.ndarray

draco.util.tools.baseline_vector(index_map, telescope)

Baseline vectors in meters.

Parameters:

• index_map (h5py.group or dict) – Index map to map into polarizations. Must contain a stack entry and an input entry.

• telescope – Telescope object containing feed information.

Returns:

bvec_m – Array of shape (2, nstack). The 2D baseline vector (in meters) for each visibility in index_map[‘stack’]

Return type:

array

draco.util.tools.calculate_redundancy(input_flags, prod_map, stack_index, nstack)

Calculates the number of redundant baselines that were stacked to form each unique baseline.

Accounts for the fact that some fraction of the inputs are flagged as bad at any given time.

Parameters:

• input_flags (np.ndarray [ninput, ntime]) – Array indicating which inputs were good at each time. Non-zero value indicates that an input was good.

• prod_map (np.ndarray[nprod]) – The products that were included in the stack. Typically found in the index_map[‘prod’] attribute of the containers.TimeStream or containers.SiderealStream object.

• stack_index (np.ndarray[nprod]) – The index of the stack axis that each product went into. Typically found in reverse_map[‘stack’][‘stack’] attribute of the containers.Timestream or containers.SiderealStream object.

• nstack (int) – Total number of unique baselines.

Returns:

redundancy – Array indicating the total number of redundant baselines with good inputs that were stacked into each unique baseline.

Return type:

np.ndarray[nstack, ntime]

draco.util.tools.cmap(i, j, n)

Given a pair of feed indices, return the pair index.

Parameters:

• i (integer) – Feed index.

• j (integer) – Feed index.

• n (integer) – Total number of feeds.

Returns:

pi – Pair index.

Return type:

integer

draco.util.tools.correct_phase_wrap(phi, deg=False)

Correct for phase wrapping.

Parameters:

• phi (np.ndarray) – Phase in radians or degrees.

• deg (bool) – Flag indicating the provided phase is in units of radians (False) or degrees (True).

Returns:

phic – Phase betwen -pi and pi if degree is False, or -180 and 180 if degree is True.

Return type:

np.ndarray

draco.util.tools.extract_diagonal(utmat, axis=1)

Extract the diagonal elements of an upper triangular array.

Parameters:

• utmat (np.ndarray[..., nprod, ...]) – Upper triangular array.

• axis (int, optional) – Axis of array that is upper triangular.

Returns:

diag – Diagonal of the array.

Return type:

np.ndarray[…, ninput, …]

draco.util.tools.find_contiguous_slices(index)

Convert indices into a list of slices.

Parameters:

index (list or array of int) – 1D indices into an array.

Returns:

slices – Slices into the array that will return all elements in index but split into contiguous regions. Useful because these contiguous slices can be used to access the desired subset of the array without making a copy.

Return type:

list of slice

draco.util.tools.find_inputs(input_index, inputs, require_match=False)

Find the indices of inputs into a list of inputs.

This behaves similarly to find_keys but will automatically choose the key to match on.

Parameters:

• input_index (np.ndarray) – Inputs to search

• inputs (np.ndarray) – Inputs to find

• require_match (bool) – Require that input_index contain every element of inputs, and if not, raise ValueError.

Returns:

indices – List of the same length as inputs containing the indices of inputs in input_inswx. If require_match is False, then this can also contain None for inputs that are not contained in input_index.

Return type:

list of int or None

draco.util.tools.find_key(key_list, key)

Find the index of a key in a list of keys.

This is a wrapper for the list method index that can search any interable (not just lists) and will return None if the key is not found.

Parameters:

• key_list (iterable) – Iterable containing keys to search

• key (object to be searched) – Keys to search for

Returns:

index – The index of key in key_list. If key_list does not contain key, then None is returned.

Return type:

int or None

draco.util.tools.find_keys(key_list, keys, require_match=False)

Find the indices of keys into a list of keys.

Parameters:

• key_list (iterable) – Iterable of keys to search

• keys (iterable) – Keys to search for

• require_match (bool) – Require that key_list contain every element of keys, and if not, raise ValueError.

Returns:

indices – List of the same length as keys containing the indices of keys in key_list. If require_match is False, then this can also contain None for keys that are not contained in key_list.

Return type:

list of int or None

draco.util.tools.icmap(ix, n)

Inverse feed map.

Parameters:

• ix (integer) – Pair index.

• n (integer) – Total number of feeds.

Returns:

fi, fj – Feed indices.

Return type:

integer

draco.util.tools.polarization_map(index_map, telescope, exclude_autos=True)

Map the visibilities corresponding to entries in pol = [‘XX’, ‘XY’, ‘YX’, ‘YY’].

Parameters:

• index_map (h5py.group or dict) – Index map to map into polarizations. Must contain a stack entry and an input entry.

• telescope – Telescope object containing feed information.

• exclude_autos (bool) – If True (default), auto-correlations are set to -1.

Returns:

polmap – Array of size nstack. Each entry is the index to the corresponding polarization in pol = [‘XX’, ‘XY’, ‘YX’, ‘YY’]

Return type:

array of int

draco.util.tools.redefine_stack_index_map(telescope, inputs, prod, stack, reverse_stack)

Ensure baselines between unmasked inputs are used to represent each stack.

Parameters:

• telescope – Telescope object containing feed information.

• inputs (np.ndarray[ninput,] of dtype=('correlator_input', 'chan_id')) – The ‘correlator_input’ or ‘chan_id’ of the inputs in the stack.

• prod (np.ndarray[nprod,] of dtype=('input_a', 'input_b')) – The correlation products as pairs of inputs.

• stack (np.ndarray[nstack,] of dtype=('prod', 'conjugate')) – The index into the prod axis of a characteristic baseline included in the stack.

• reverse_stack (np.ndarray[nprod,] of dtype=('stack', 'conjugate')) – The index into the stack axis that each prod belongs.

Returns:

• stack_new (np.ndarray[nstack,] of dtype=(‘prod’, ‘conjugate’)) – The updated stack index map, where each element is an index to a product consisting of a pair of unmasked inputs.

• stack_flag (np.ndarray[nstack,] of dtype=bool) – Boolean flag that is True if this element of the stack index map is now valid, and False if none of the baselines that were stacked contained unmasked inputs.

draco.util.tools.taper_mask(mask, nwidth, outer=False)

Taper a 2d mask along the last axis.

Parameters:

• mask (np.ndarray) – Mask to taper

• nwidth (int) – Number of samples on either side of the mask to taper

• outer (bool, optional) – If True, expand the mask outwards (wider). Otherwise, expand the mask inwards (narrower). Default is False

Returns:

tapered_mask – Mask convolved with taper window

Return type:

np.ndarray[np.float64]

draco.util.tools.window_generalised(x, window='nuttall')

A generalised high-order window at arbitrary locations.

Parameters:

• x (np.ndarray[n]) – Location to evaluate at. Values outside the range 0 to 1 are zero.

• window (str) – Type of window function to return. Must be one of the following strings: ‘uniform’, ‘hann’, ‘hanning’, ‘hamming’, ‘blackman’, ‘nuttall’, ‘blackman_nuttall’, ‘blackman_harris’, ‘triangular’, or ‘tukey-0.X’. If “tukey-0.X”, then 0.X is the fraction of the full window that will be tapered.

Returns:

w – Window function.

Return type:

np.ndarray[n]