Visread API#

Visread tools without a casatools dependency

Process#

visread.process.safe_baseline_constant_meters(uu, vv, freqs, cell_size, npix, uv_cell_frac=0.05)[source]#

This routine determines whether the baselines can safely be assumed to be constant with channel when they converted from meters to units of kilolambda.

The antenna baselines are the same as a function of channel when they are measured in physical distance units, such as meters. However, when these baselines are converted to spatial frequency units, via

\[u = \frac{D}{\lambda},\]

it’s possible that the \(u\) and \(v\) values of each channel are significantly different if the \(\lambda\) values of each channel are significantly different. This routine evaluates whether the maximum change in \(u\) or \(v\) across channels (when represented in kilolambda) is smaller than some threshold value, calculated as the fraction of a \(u,v\) cell defined by coords.

If this function returns True, then it would be safe to proceed with parallelization in the mpol.fourier.NuFFT layer via the coil dimension.

Parameters:

  • uu (1D np.array) – a 1D array of length nvis array of the u (East-West) spatial frequency coordinate in units of [m]

  • vv (1D np.array) – a 1D array of length nvis array of the v (North-South) spatial frequency coordinate in units of [m]

  • freqs (1D np.array) – a 1D array of length nchan of the channel frequencies, in units of [Hz].

  • coords (mpol.coordinates.GridCoords) – object which represents the image and uv-grid dimensions.

  • uv_cell_frac (float) – the maximum threshold for a change in \(u\) or \(v\) spatial frequency across channels, measured as a fraction of the \(u,v\) cell defined by coords.

Returns:

True if it is safe to assume that the baselines are constant with channel (at a tolerance of uv_cell_frac.) Otherwise returns False.

Return type:

boolean

visread.process.safe_baseline_constant_kilolambda(uu, vv, cell_size, npix, uv_cell_frac=0.05)[source]#

This routine determines whether the baselines can safely be assumed to be constant with channel, when the are represented in units of kilolambda.

Compared to mpol.fourier.safe_baseline_constant_meters, this function works with multidimensional arrays of uu and vv that are shape (nchan, nvis) and have units of kilolambda.

If this routine returns True, then it should be safe for the user to either average the baselines across channel or simply choose a single, representative channel. This would enable parallelization in the {class}`mpol.fourier.NuFFT` via the coil dimension.

Parameters:

  • uu (1D np.array) – a 1D array of length nvis array of the u (East-West) spatial frequency coordinate in units of [m]

  • vv (1D np.array) – a 1D array of length nvis array of the v (North-South) spatial frequency coordinate in units of [m]

  • freqs (1D np.array) – a 1D array of length nchan of the channel frequencies, in units of [Hz].

  • coords – a mpol.coordinates.GridCoords object which represents the image and uv-grid dimensions.

  • uv_cell_frac (float) – the maximum threshold for a change in \(u\) or \(v\) spatial frequency across channels, measured as a fraction of the \(u,v\) cell defined by coords.

Returns:

True if it is safe to assume that the baselines are constant with

channel (at a tolerance of uv_cell_frac.) Otherwise returns False.

Return type:

boolean

visread.process.convert_baselines(baselines, freq)[source]#

Convert baselines in meters to lambda. Assumes that baselines and freq will broadcast under division.

Parameters:

  • baselines (float or np.array) – baselines in [m].

  • freq (float or np.array) – frequencies in [Hz]. If either baselines or freq are numpy arrays, their shapes must be broadcast-able.

Returns:

baselines in [lambda]

Return type:

(1D array nvis)

visread.process.broadcast_and_convert_baselines(u, v, chan_freq)[source]#

Convert baselines to lambda and broadcast to match shape of channel frequencies.

Parameters:

  • u (1D array nvis) – baseline [m]

  • v (1D array nvis) – baseline [m]

  • chan_freq (1D array nchan) – frequencies [Hz]

Returns:

(u, v) each of which are (nchan, nvis) arrays of baselines in [lambda]

visread.process.broadcast_weights(weight, data_shape, chan_axis=0)[source]#

Broadcast a vector of non-channelized weights to match the shape of the visibility data that is channelized (e.g., for spectral line applications) but already averaged over polarizations.

Parameters:

  • weight (np.array) – the weights

  • data_shape (tuple) – the shape of the data

  • chan_axis (int) – the axis which represents the number of channels in the data array, typically 0 for visibility data that has already been averaged over polarizations.

Returns:

np.array (float) array of weights the same shape as the data

visread.process.weight_to_sigma(weight)[source]#

Convert a weight (\(w\)) to an uncertainty (\(\sigma\)) using

\[\sigma = \sqrt{1/w}\]
Parameters:

weight (float or np.array) – statistical weight value

Returns:

the corresponding uncertainty

Return type:

sigma (float or np.array)

visread.process.rescale_weights(weight, sigma_rescale)[source]#

Rescale all weights by a common factor. It would be as if \(\sigma\) were rescaled by this factor.

\[w_\mathrm{new} = w_\mathrm{old} / \sigma_\mathrm{rescale}^2\]
Parameters:

  • weight (float or np.array) – the weights

  • sigma_rescale (float) – the factor by which to rescale the weight

Returns:

(float or np.array) the rescaled weights

visread.process.average_data_polarization(data, weight, polarization_axis=0)[source]#

Perform a weighted average of the data over the polarization axis.

Parameters:

  • data (npol, nchan, nvis) – complex data array. Could either be real data or model_data.

  • weight (npol, nvis) – weight array matching data array (before broadcast)

  • polarization_axis (int) – index of the polarization axis, typically 0.

Returns:

data averaged over the polarization axis.

visread.process.average_weight_polarization(weight, polarization_axis=0)[source]#

Average the weights over the polarization axis.

Parameters:

  • weight (np.array) – weight array. Could be shape (2, nchan, nvis) or just (2, nvis), dependending on whether it has been broadcasted already.

  • polarization_axis (int) – the polarization axis, typically 0.

Returns:

weight array summed over the polarization axis. Could be shape (nchan, nvis) or just (nvis) depending on whether it was broadcasted across channels.

Return type:

(np.array)

visread.process.average_flag_polarization(flag, polarization_axis=0)[source]#

Collapse the flags across the polarization axis, taking the approach that if either polarization is flagged, the averaged product shoud be flagged too.

Parameters:

  • flag (np.array bool) – flag array. Could be multidimensional, e.g. (2, nchan, nvis) or just (2, nvis).

  • polarization_axis (int) – the polarization axis, typically 0.

Returns:

flag array collapsed across the polarization axis. Could be shape (nchan, nvis) or just (nvis) depending on whether it was broadcasted across channels.

Return type:

(np.array bool)

visread.process.contains_autocorrelations(ant1, ant2)[source]#

Test whether the list of antennas contain any autocorrelations.

Parameters:

  • ant1 (np.array int) – antenna 1

  • ant2 (np.array int) – antenna 2

Returns:

True if list contains autocorrelation pairs.

Return type:

boolean

visread.process.isdecreasing(chan_freq)[source]#

Return true if channels are stored in decreasing frequency order, i.e., blueshifted to redshifted.

Parameters:

chan_freq (1D numpy array) – the channel frequencies in Hz

Returns:

True if channels are stored in decreasing frequency order (preferred order).

Return type:

boolean

Scatter#

visread.scatter.calculate_rescale_factor(s, method='Nelder-Mead', bins=40)[source]#

Calculate the multiplicative factor needed to scale \(\sigma\) such that the scatter in the residuals matches that expected from a Gaussian.

Parameters:

  • s (np.array) – an array of residuals normalized to their \(\sigma\) values. Assumes values are float.

  • method (string) – string passed to scipy.optimize.minimize to choose minimization argument.

  • bins (int) – number of bins to use in the histogram

Returns:

the multiplicative factor needed to multiply against \(\sigma\)

Return type:

float

visread.scatter.get_averaged_scatter(data, model_data, weight, flag=None)[source]#

Calculate the scatter of the residual visibilities, assuming they have already been averaged across polarization.

Parameters:

  • data (np.array complex) – the data visibilities

  • model_data (np.array complex) – the model visibilities

  • weight (np.array real) – the statistical weight of the uncertainties

  • flag (np.array bool) – the flags of the dataset, in original format (True should be flagged).

Returns:

the scatter of the residual visibilities in units of \(\sigma\)

Return type:

np.array

Visualization#

visread.visualization.plot_baselines(u, v, title=None)[source]#

Make a plot of the baselines.

Parameters:

  • u – baseline in meters

  • v – baseline in meters.

Returns:

matplotlib.fig

visread.visualization.scatter_hist(scatter_XX, scatter_YY, log=False, **kwargs)[source]#
Parameters:

  • scatter_XX (1D numpy array) –

  • scatter_YY (1D numpy array) –

Returns:

matplotlib figure

Utils#

visread.utils.doppler_shift(freq, v)[source]#

Calculate the relativistic doppler shift. Negative velocities mean that the frequencies will be blueshifted.

Parameters:

  • freq (float or np.array) – the frequencies in units of Hz.

  • v (float or np.array) – the velocities in units of m/s. If either freq or v are arrays, they must have broadcast-able shapes.

Returns:

shifted frequencies

visread.utils.gaussian(x, sigma=1)[source]#

Evaluate a reference Gaussian as a function of \(x\)

Parameters:

  • x (float) – location to evaluate Gaussian

  • sigma (float) – standard deviation of Gaussion (default 1)

The Gaussian is defined as

\[f(x) = \frac{1}{\sigma \sqrt{2 \pi}} \exp \left ( -\frac{x^2}{2 \sigma^2}\right )\]
Returns:

Gaussian function evaluated at \(x\)