Gridding and Degridding

This section contains routines for

  1. Gridding complex visibilities onto an image.
  2. Degridding complex visibilities from an image.

Simple

Gridding with no correction for the W-term.

Numpy

grid(vis, uvw, flags, weights, ref_wave, …) Convolutional gridder which grids visibilities vis at the specified uvw coordinates and ref_wave reference wavelengths using the specified convolution_filter.
degrid(grid, uvw, weights, ref_wave, …[, …]) Convolutional degridder (continuum)
africanus.gridding.simple.grid(vis, uvw, flags, weights, ref_wave, convolution_filter, cell_size, nx=1024, ny=1024, grid=None)[source]

Convolutional gridder which grids visibilities vis at the specified uvw coordinates and ref_wave reference wavelengths using the specified convolution_filter.

Variable numbers of correlations are supported.

  • (row, chan, corr_1, corr_2) vis will result in a (ny, nx, corr_1, corr_2) grid.
  • (row, chan, corr_1) vis will result in a (ny, nx, corr_1) grid.
Parameters:
vis : np.ndarray

complex visibility array of shape (row, chan, corr_1, corr_2)

uvw : np.ndarray

float64 array of UVW coordinates of shape (row, 3) in wavelengths.

weights : np.ndarray

float32 or float64 array of weights. Set this to np.ones_like(vis, dtype=np.float32) as default.

flags : np.ndarray

flagged array of shape (row, chan, corr_1, corr_2). Any positive quantity will indicate that the corresponding visibility should be flagged. Set to np.zeros_like(vis, dtype=np.bool) as default.

ref_wave : np.ndarray

float64 array of wavelengths of shape (chan,)

convolution_filter : ConvolutionFilter

Convolution filter

cell_size : float

Cell size in arcseconds.

nx : integer, optional

Size of the grid’s X dimension

ny : integer, optional

Size of the grid’s Y dimension

grid : np.ndarray, optional

complex64/complex128 array of shape (ny, nx, corr_1, corr_2) If supplied, this array will be used as the gridding target, and nx and ny will be derived from this grid’s dimensions.

Returns:
np.ndarray

(ny, nx, corr_1, corr_2) complex ndarray of gridded visibilities. The number of correlations may vary, depending on the shape of vis.

africanus.gridding.simple.degrid(grid, uvw, weights, ref_wave, convolution_filter, cell_size, dtype=<type 'numpy.complex64'>)[source]

Convolutional degridder (continuum)

Variable numbers of correlations are supported.

  • (ny, nx, corr_1, corr_2) grid will result in a (row, chan, corr_1, corr_2) vis
  • (ny, nx, corr_1) grid will result in a (row, chan, corr_1) vis
Parameters:
grid : np.ndarray

float or complex grid of visibilities of shape (ny, nx, corr_1, corr_2)

uvw : np.ndarray

float64 array of UVW coordinates of shape (row, 3) in wavelengths.

weights : np.ndarray

float32 or float64 array of weights. Set this to np.ones_like(vis, dtype=np.float32) as default.

ref_wave : np.ndarray

float64 array of wavelengths of shape (chan,)

convolution_filter : ConvolutionFilter

Convolution Filter

cell_size : float

Cell size in arcseconds.

dtype : numpy.dtype

Data type of the visibilities

Returns:
np.ndarray

(row, chan, corr_1, corr_2) complex ndarray of visibilities

Dask

grid(vis, uvw, flags, weights, ref_wave, …) Convolutional gridder which grids visibilities vis at the specified uvw coordinates and ref_wave reference wavelengths using the specified convolution_filter.
degrid(grid, uvw, weights, ref_wave, …) Convolutional degridder (continuum)
africanus.gridding.simple.dask.grid(vis, uvw, flags, weights, ref_wave, convolution_filter, cell_size, nx=1024, ny=1024)[source]

Convolutional gridder which grids visibilities vis at the specified uvw coordinates and ref_wave reference wavelengths using the specified convolution_filter.

Variable numbers of correlations are supported.

  • (row, chan, corr_1, corr_2) vis will result in a (ny, nx, corr_1, corr_2) grid.
  • (row, chan, corr_1) vis will result in a (ny, nx, corr_1) grid.
Parameters:
vis : np.ndarray

complex visibility array of shape (row, chan, corr_1, corr_2)

uvw : np.ndarray

float64 array of UVW coordinates of shape (row, 3) in wavelengths.

weights : np.ndarray

float32 or float64 array of weights. Set this to da.ones_like(vis, dtype=np.float32) as default.

flags : np.ndarray

flagged array of shape (row, chan, corr_1, corr_2). Any positive quantity will indicate that the corresponding visibility should be flagged. Set to da.zeros_like(vis, dtype=np.bool) as default.

ref_wave : np.ndarray

float64 array of wavelengths of shape (chan,)

convolution_filter : ConvolutionFilter

Convolution filter

cell_size : float

Cell size in arcseconds.

nx : integer, optional

Size of the grid’s X dimension

ny : integer, optional

Size of the grid’s Y dimension

grid : np.ndarray, optional

complex64/complex128 array of shape (ny, nx, corr_1, corr_2) If supplied, this array will be used as the gridding target, and nx and ny will be derived from this grid’s dimensions.

Returns:
np.ndarray

(ny, nx, corr_1, corr_2) complex ndarray of gridded visibilities. The number of correlations may vary, depending on the shape of vis.

africanus.gridding.simple.dask.degrid(grid, uvw, weights, ref_wave, convolution_filter, cell_size)[source]

Convolutional degridder (continuum)

Variable numbers of correlations are supported.

  • (ny, nx, corr_1, corr_2) grid will result in a (row, chan, corr_1, corr_2) vis
  • (ny, nx, corr_1) grid will result in a (row, chan, corr_1) vis
Parameters:
grid : np.ndarray

float or complex grid of visibilities of shape (ny, nx, corr_1, corr_2)

uvw : np.ndarray

float64 array of UVW coordinates of shape (row, 3) in wavelengths.

weights : np.ndarray

float32 or float64 array of weights. Set this to da.ones_like(vis, dtype=np.float32) as default.

ref_wave : np.ndarray

float64 array of wavelengths of shape (chan,)

convolution_filter : ConvolutionFilter

Convolution Filter

cell_size : float

Cell size in arcseconds.

dtype : numpy.dtype

Data type of the visibilities

Returns:
np.ndarray

(row, chan, corr_1, corr_2) complex ndarray of visibilities

W Stacking

This is currently experimental

Implements W-Stacking as described in WSClean.

w_stacking_layers(w_min, w_max, l, m) Computes the number of w-layers given the minimum and maximum W coordinates, as well as the l and m coordinates.
w_stacking_bins(w_min, w_max, w_layers) Returns the W coordinate bins appropriate for the observation parameters, given the minimum and maximum W coordinates and the number of W layers.
w_stacking_centroids(w_bins) Returns the W coordinate centroids for each W layer.
grid(vis, uvw, flags, weights, ref_wave, …) Convolutional W-stacking gridder.
degrid(grids, uvw, weights, ref_wave, …[, …]) Convolutional W-stacking degridder (continuum)
africanus.gridding.wstack.w_stacking_layers(w_min, w_max, l, m)[source]

Computes the number of w-layers given the minimum and maximum W coordinates, as well as the l and m coordinates.

\[N_{wlay} >> 2 \pi \left(w_{max} - w_{min} \right) \underset{l, m}{\max}\left(1 - \sqrt{1 - l^2 - m^2}\right)\]
Parameters:
w_min : float

Minimum W coordinate in wavelengths.

w_max : float

Maximum W coordinate in wavelengths.

l : numpy.ndarray

l coordinates

m : numpy.ndarray

m coordinates

Returns:
int

Number of w-layers

africanus.gridding.wstack.w_stacking_bins(w_min, w_max, w_layers)[source]

Returns the W coordinate bins appropriate for the observation parameters, given the minimum and maximum W coordinates and the number of W layers.

W coordinates can be binned by calling

w_bins = np.digitize(w, bins) - 1
Parameters:
w_min : float

Minimum W coordinate in wavelengths.

w_max : float

Maximum W coordinate in wavelengths.

w_layers : int

Number of w layers

Returns:
:class:`numpy.ndarray`

W-coordinate bins of shape (nw + 1,).

Notes

A small epsilon is added to w_max to force this W coordinate into the last bin.

africanus.gridding.wstack.w_stacking_centroids(w_bins)[source]

Returns the W coordinate centroids for each W layer. Computed from bins produced by w_stacking_bins().

Parameters:
w_bins : numpy.ndarray

W stacking bins of shape (nw + 1,)

Returns:
:class:`numpy.ndarray`

W-coordinate centroids of shape (nw,) in wavelengths.

africanus.gridding.wstack.grid(vis, uvw, flags, weights, ref_wave, convolution_filter, w_bins, cell_size, nx=1024, ny=1024, grids=None)[source]

Convolutional W-stacking gridder.

This function grids visibilities vis onto multiple grids, each associated with a W-layer defined by w_bins. The W coordinate of the uvw array is used to bin the visibility into the appropriate grid.

Variable numbers of correlations are supported.

  • (row, chan, corr_1, corr_2) vis will result in a (ny, nx, corr_1, corr_2) grid.
  • (row, chan, corr_1) vis will result in a (ny, nx, corr_1) grid.
Parameters:
vis : numpy.ndarray

complex visibility array of shape (row, chan, corr_1, corr_2)

uvw : numpy.ndarray

float64 array of UVW coordinates of shape (row, 3)

weights : numpy.ndarray

float32 or float64 array of weights. Set this to np.ones_like(vis, dtype=np.float32) as default.

flags : np.ndarray

flagged array of shape (row, chan, corr_1, corr_2). Any positive quantity will indicate that the corresponding visibility should be flagged. Set to np.zeros_like(vis, dtype=np.bool) as default.

ref_wave : np.ndarray

float64 array of wavelengths of shape (chan,)

convolution_filter : ConvolutionFilter

Convolution filter

w_bins : numpy.ndarray

W coordinate bins of shape (nw + 1,)

cell_size : float

Cell size in arcseconds.

nx : integer, optional

Size of the grid’s X dimension

ny : integer, optional

Size of the grid’s Y dimension

grids : list of np.ndarray, optional

list of complex arrays of length nw, each with shape (ny, nx, corr_1, corr_2). If supplied, this array will be used as the gridding target, and nx and ny will be derived from the grid’s dimensions.

Returns:
list of np.ndarray

list of complex arrays of gridded visibilities, of length nw, each with shape (ny, nx, corr_1, corr_2). The number of correlations may vary, depending on the shape of vis.

africanus.gridding.wstack.degrid(grids, uvw, weights, ref_wave, convolution_filter, w_bins, cell_size, dtype=<type 'numpy.complex64'>)[source]

Convolutional W-stacking degridder (continuum)

Variable numbers of correlations are supported.

  • (ny, nx, corr_1, corr_2) grid will result in a (row, chan, corr_1, corr_2) vis
  • (ny, nx, corr_1) grid will result in a (row, chan, corr_1) vis
Parameters:
grids : list of np.ndarray

list of visibility grids of length nw. of shape (ny, nx, corr_1, corr_2)

uvw : np.ndarray

float64 array of UVW coordinates of shape (row, 3)

weights : np.ndarray

float32 or float64 array of weights. Set this to np.ones_like(vis, dtype=np.float32) as default.

ref_wave : np.ndarray

float64 array of wavelengths of shape (chan,)

convolution_filter : ConvolutionFilter

Convolution Filter

w_bins : numpy.ndarray

W coordinate bins of shape (nw + 1,)

cell_size : float

Cell size in arcseconds.

dtype : numpy.dtype, optional

Numpy type of the resulting array. Defaults to numpy.complex64.

Returns:
np.ndarray

(row, chan, corr_1, corr_2) complex ndarray of visibilities

Utilities

estimate_cell_size(u, v, wavelength[, …]) Estimate the cell size in arcseconds given baseline u and v coordinates, as well as the wavelengths, \(\lambda\).
africanus.gridding.util.estimate_cell_size(u, v, wavelength, factor=3.0, ny=None, nx=None)[source]

Estimate the cell size in arcseconds given baseline u and v coordinates, as well as the wavelengths, \(\lambda\).

The cell size is computed as:

\[ \begin{align}\begin{aligned}\Delta u = 1.0 / \left( 2 \times \text{ factor } \times \max (\vert u \vert) / \min( \lambda) \right)\\\Delta v = 1.0 / \left( 2 \times \text{ factor } \times \max (\vert v \vert) / \min( \lambda) \right)\end{aligned}\end{align} \]

If ny and nx are provided the following checks are performed and exceptions are raised on failure:

\[ \begin{align}\begin{aligned}\Delta u * \text{ ny } \leq \min (\lambda) / \min (\vert u \vert)\\\Delta v * \text{ nx } \leq \min (\lambda) / \min (\vert v \vert)\end{aligned}\end{align} \]
Parameters:
u : numpy.ndarray or float

Maximum u coordinate in metres.

v : numpy.ndarray or float

Maximum v coordinate in metres.

wavelength : numpy.ndarray or float

Wavelengths, in metres.

factor : float, optional

Scaling factor

ny : int, optional

Grid y dimension

nx : int, optional

Grid x dimension

Returns:
:class:`numpy.ndarray`

Cell size of u and v in arcseconds with shape (2,)

Raises:
ValueError

If the cell size criteria are not matched.