Gridding and Degridding#

This section contains routines for

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

Nifty#

Dask#

`grid_config`([nx, ny, eps, cell_size_x, ...])	Returns a wrapper around a NIFTY GridderConfiguration object.
`grid`(vis, uvw, flags, weights, frequencies, ...)	Grids the supplied visibilities in parallel.
`dirty`(grid, grid_config)	Computes the dirty image from gridded visibilities and the gridding configuration.
`degrid`(grid, uvw, flags, weights, ...[, ...])	Degrids the visibilities from the supplied grid in parallel.
`model`(image, grid_config)	Computes model visibilities from an image and a gridding configuration.

africanus.gridding.nifty.dask.grid_config(nx=1024, ny=1024, eps=2e-13, cell_size_x=2.0, cell_size_y=2.0)[source]#

Returns a wrapper around a NIFTY GridderConfiguration object.

Parameters:

nxint, optional: Number of X pixels in the grid. Defaults to 1024.
nyint, optional: Number of Y pixels in the grid. Defaults to 1024.
cell_size_xfloat, optional: Cell size of the X pixel in arcseconds. Defaults to 2.0.
cell_size_yfloat, optional: Cell size of the Y pixel in arcseconds. Defaults to 2.0.
epsfloat: Gridder accuracy error. Defaults to 2e-13

Returns:

grid_configGridderConfigWrapper: The NIFTY Gridder Configuration

africanus.gridding.nifty.dask.grid(vis, uvw, flags, weights, frequencies, grid_config, wmin=-1e+30, wmax=1e+30, streams=None)[source]#

Grids the supplied visibilities in parallel. Note that a grid is create for each visibility chunk.

Parameters:

visdask.array.Array: visibilities of shape (row, chan, corr)
uvwdask.array.Array: uvw coordinates of shape (row, 3)
flagsdask.array.Array: flags of shape (row, chan, corr)
weightsdask.array.Array: weights of shape (row, chan, corr).
frequenciesdask.array.Array: frequencies of shape (chan,)
grid_configGridderConfigWrapper: Gridding Configuration
wminfloat: Minimum W coordinate to grid. Defaults to -1e30.
wmaxfloat: Maximum W coordinate to grid. Default to 1e30.
streamsint, optional: Number of parallel gridding operations. Default to None, in which case as many grids as visibility chunks will be created.

Returns:

griddask.array.Array: grid of shape (ny, nx, corr)

africanus.gridding.nifty.dask.dirty(grid, grid_config)[source]#

Computes the dirty image from gridded visibilities and the gridding configuration.

Parameters:

griddask.array.Array: Gridded visibilities of shape (nv, nu, ncorr)
grid_configGridderConfigWrapper: Gridding configuration

Returns:

dirtydask.array.Array: dirty image of shape (ny, nx, corr)

africanus.gridding.nifty.dask.degrid(grid, uvw, flags, weights, frequencies, grid_config, wmin=-1e+30, wmax=1e+30)[source]#

Degrids the visibilities from the supplied grid in parallel.

Parameters:

griddask.array.Array: gridded visibilities of shape (ny, nx, corr)
uvwdask.array.Array: uvw coordinates of shape (row, 3)
flagsdask.array.Array: flags of shape (row, chan, corr)
weightsdask.array.Array: weights of shape (row, chan, corr). Currently unsupported and ignored.
frequenciesdask.array.Array: frequencies of shape (chan,)
grid_configGridderConfigWrapper: Gridding Configuration
wminfloat: Minimum W coordinate to grid. Defaults to -1e30.
wmaxfloat: Maximum W coordinate to grid. Default to 1e30.

Returns:

griddask.array.Array: grid of shape (ny, nx, corr)

africanus.gridding.nifty.dask.model(image, grid_config)[source]#

Computes model visibilities from an image and a gridding configuration.

Parameters:

imagedask.array.Array: Image of shape (ny, nx, corr).
grid_configGridderConfigWrapper: nifty gridding configuration object

Returns:

model_visdask.array.Array: Model visibilities of shape (nu, nv, corr).

wgridder#

Wrappers around ‘ducc.wgridder <https://gitlab.mpcdf.mpg.de/mtr/ducc>`_.

Numpy#

`dirty`(uvw, freq, vis, freq_bin_idx, ...[, ...])	Compute visibility to image mapping using ducc gridder i.e.
`model`(uvw, freq, image, freq_bin_idx, ...[, ...])	Compute image to visibility mapping using ducc degridder i.e.
`residual`(uvw, freq, image, vis, ...[, ...])	Compute residual image given a model and visibilities using ducc degridder i.e.
`hessian`(uvw, freq, image, freq_bin_idx, ...)	Compute action of Hessian on an image using ducc

africanus.gridding.wgridder.dirty(uvw, freq, vis, freq_bin_idx, freq_bin_counts, nx, ny, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]#

Compute visibility to image mapping using ducc gridder i.e.

\[I^D = R^\dagger \Sigma^{-1} V\]

where \(R^\dagger\) is an implicit gridding operator, \(V\) denotes visibilities of shape (row, chan) and \(I^D\) is the dirty image of shape (band, nx, ny).

The number of imaging bands (band) must be less than or equal to the number of channels (chan) at which the data were obtained. The mapping from (chan) to (band) is described by freq_bin_idx and freq_bin_counts as described below.

Note that, if self adjoint gridding and degridding operators are required then weights should be the square root of what is typically referred to as imaging weights and should also be passed into the degridder. In this case, the data needs to be pre-whitened.

Parameters:

uvwnumpy.ndarray: uvw coordinates at which visibilities were obtained with shape (row, 3).
freqnumpy.ndarray: Observational frequencies of shape (chan,).
visnumpy.ndarray: Visibilities of shape (row,chan).
freq_bin_idxnumpy.ndarray: Starting indices of frequency bins for each imaging band of shape (band,).
freq_bin_countsnumpy.ndarray: The number of channels in each imaging band of shape (band,).
cellfloat: The cell size of a pixel along the \(x\) direction in radians.
weightsnumpy.ndarray, optional: Imaging weights of shape (row, chan).
flag: :class:`numpy.ndarray`, optional: Flags of shape (row,chan). Will only process visibilities for which flag!=0
cellyfloat, optional: The cell size of a pixel along the \(y\) direction in radians. By default same as cell size along \(x\) direction.
epsilonfloat, optional: The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.
nthreadsint, optional: The number of threads to use. Defaults to one. If set to zero will use all available cores.
do_wstackingbool, optional: Whether to correct for the w-term or not. Defaults to True
double_accumbool, optional: If true ducc will accumulate in double precision regardless of the input type.

Returns:

modelnumpy.ndarray: Dirty image corresponding to visibilities of shape (nband, nx, ny).

africanus.gridding.wgridder.model(uvw, freq, image, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True)[source]#

Compute image to visibility mapping using ducc degridder i.e.

\[V = Rx\]

where \(R\) is an implicit degridding operator, \(V\) denotes visibilities of shape (row, chan) and \(x\) is the image of shape (band, nx, ny).

The number of imaging bands (band) has to be less than or equal to the number of channels (chan) at which the data were obtained. The mapping from (chan) to (band) is described by freq_bin_idx and freq_bin_counts as described below.

There is an option to provide weights during degridding to cater for self adjoint gridding and degridding operators. In this case weights should actually be the square root of what is typically referred to as imaging weights. In this case the degridder computes the whitened model visibilities i.e.

\[V = \Sigma^{-\frac{1}{2}} R x\]

where \(\Sigma\) refers to the inverse of the weights (i.e. the data covariance matrix when using natural weighting).

Parameters:

uvwnumpy.ndarray: uvw coordinates at which visibilities were obtained with shape (row, 3).
freqnumpy.ndarray: Observational frequencies of shape (chan,).
modelnumpy.ndarray: Model image to degrid of shape (nband, nx, ny).
freq_bin_idxnumpy.ndarray: Starting indices of frequency bins for each imaging band of shape (band,).
freq_bin_countsnumpy.ndarray: The number of channels in each imaging band of shape (band,).
cellfloat: The cell size of a pixel along the \(x\) direction in radians.
weightsnumpy.ndarray, optional: Imaging weights of shape (row, chan).
flag: :class:`numpy.ndarray`, optional: Flags of shape (row,chan). Will only process visibilities for which flag!=0
cellyfloat, optional: The cell size of a pixel along the \(y\) direction in radians. By default same as cell size along \(x\) direction.
epsilonfloat, optional: The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.
nthreadsint, optional: The number of threads to use. Defaults to one. If set to zero will use all available cores.
do_wstackingbool, optional: Whether to correct for the w-term or not. Defaults to True

Returns:

visnumpy.ndarray: Visibilities corresponding to model of shape (row,chan).

africanus.gridding.wgridder.residual(uvw, freq, image, vis, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]#

Compute residual image given a model and visibilities using ducc degridder i.e.

\[I^R = R^\dagger \Sigma^{-1}(V - Rx)\]

where \(R\) is an implicit degridding operator, \(V\) denotes visibilities of shape (row, chan) and \(x\) is the image of shape (band, nx, ny).

Note that, if the gridding and degridding operators both apply the square root of the imaging weights then the visibilities that are passed in should be pre-whitened. In this case the function computes

\[I^R = R^\dagger \Sigma^{-\frac{1}{2}}(\tilde{V} - \Sigma^{-\frac{1}{2}}Rx)\]

which is identical to the above expression if \(\tilde{V} = \Sigma^{-\frac{1}{2}}V\).

Parameters:

uvwnumpy.ndarray: uvw coordinates at which visibilities were obtained with shape (row, 3).
freqnumpy.ndarray: Observational frequencies of shape (chan,).
modelnumpy.ndarray: Model image to degrid of shape (band, nx, ny).
visnumpy.ndarray: Visibilities of shape (row,chan).
weightsnumpy.ndarray: Imaging weights of shape (row, chan).
freq_bin_idxnumpy.ndarray: Starting indices of frequency bins for each imaging band of shape (band,).
freq_bin_countsnumpy.ndarray: The number of channels in each imaging band of shape (band,).
cellfloat: The cell size of a pixel along the \(x\) direction in radians.
flag: :class:`numpy.ndarray`, optional: Flags of shape (row,chan). Will only process visibilities for which flag!=0
cellyfloat, optional: The cell size of a pixel along the \(y\) direction in radians. By default same as cell size along \(x\) direction.
nuint, optional: The number of pixels in the padded grid along the \(x\) direction. Chosen automatically by default.
nvint, optional: The number of pixels in the padded grid along the \(y\) direction. Chosen automatically by default.
epsilonfloat, optional: The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.
nthreadsint, optional: The number of threads to use. Defaults to one.
do_wstackingbool, optional: Whether to correct for the w-term or not. Defaults to True
double_accumbool, optional: If true ducc will accumulate in double precision regardless of the input type.

Returns:

residualnumpy.ndarray: Residual image corresponding to model of shape (band, nx, ny).

africanus.gridding.wgridder.hessian(uvw, freq, image, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]#

Compute action of Hessian on an image using ducc

\[R^\dagger \Sigma^{-1} R x\]

where \(R\) is an implicit degridding operator and \(x\) is the image of shape (band, nx, ny).

Parameters:

uvwnumpy.ndarray: uvw coordinates at which visibilities were obtained with shape (row, 3).
freqnumpy.ndarray: Observational frequencies of shape (chan,).
modelnumpy.ndarray: Model image to degrid of shape (band, nx, ny).
weightsnumpy.ndarray: Imaging weights of shape (row, chan).
freq_bin_idxnumpy.ndarray: Starting indices of frequency bins for each imaging band of shape (band,).
freq_bin_countsnumpy.ndarray: The number of channels in each imaging band of shape (band,).
cellfloat: The cell size of a pixel along the \(x\) direction in radians.
flag: :class:`numpy.ndarray`, optional: Flags of shape (row,chan). Will only process visibilities for which flag!=0
cellyfloat, optional: The cell size of a pixel along the \(y\) direction in radians. By default same as cell size along \(x\) direction.
nuint, optional: The number of pixels in the padded grid along the \(x\) direction. Chosen automatically by default.
nvint, optional: The number of pixels in the padded grid along the \(y\) direction. Chosen automatically by default.
epsilonfloat, optional: The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.
nthreadsint, optional: The number of threads to use. Defaults to one.
do_wstackingbool, optional: Whether to correct for the w-term or not. Defaults to True
double_accumbool, optional: If true ducc will accumulate in double precision regardless of the input type.

Returns:

residualnumpy.ndarray: Residual image corresponding to model of shape (band, nx, ny).

Dask#

`dirty`(uvw, freq, vis, freq_bin_idx, ...[, ...])	Compute visibility to image mapping using ducc gridder i.e.
`model`(uvw, freq, image, freq_bin_idx, ...[, ...])	Compute image to visibility mapping using ducc degridder i.e.
`residual`(uvw, freq, image, vis, ...[, ...])	Compute residual image given a model and visibilities using ducc degridder i.e.
`hessian`(uvw, freq, image, freq_bin_idx, ...)	Compute action of Hessian on an image using ducc

africanus.gridding.wgridder.dask.dirty(uvw, freq, vis, freq_bin_idx, freq_bin_counts, nx, ny, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]#

Compute visibility to image mapping using ducc gridder i.e.

\[I^D = R^\dagger \Sigma^{-1} V\]

where \(R^\dagger\) is an implicit gridding operator, \(V\) denotes visibilities of shape (row, chan) and \(I^D\) is the dirty image of shape (band, nx, ny).

Parameters:

uvwdask.array.Array: uvw coordinates at which visibilities were obtained with shape (row, 3).
freqdask.array.Array: Observational frequencies of shape (chan,).
visdask.array.Array: Visibilities of shape (row,chan).
freq_bin_idxdask.array.Array: Starting indices of frequency bins for each imaging band of shape (band,).
freq_bin_countsdask.array.Array: The number of channels in each imaging band of shape (band,).
cellfloat: The cell size of a pixel along the \(x\) direction in radians.
weightsdask.array.Array, optional: Imaging weights of shape (row, chan).
flag: :class:`dask.array.Array`, optional: Flags of shape (row,chan). Will only process visibilities for which flag!=0
cellyfloat, optional: The cell size of a pixel along the \(y\) direction in radians. By default same as cell size along \(x\) direction.
epsilonfloat, optional: The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.
nthreadsint, optional: The number of threads to use. Defaults to one. If set to zero will use all available cores.
do_wstackingbool, optional: Whether to correct for the w-term or not. Defaults to True
double_accumbool, optional: If true ducc will accumulate in double precision regardless of the input type.

Returns:

modeldask.array.Array: Dirty image corresponding to visibilities of shape (nband, nx, ny).

africanus.gridding.wgridder.dask.model(uvw, freq, image, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True)[source]#

Compute image to visibility mapping using ducc degridder i.e.

\[V = Rx\]

where \(R\) is an implicit degridding operator, \(V\) denotes visibilities of shape (row, chan) and \(x\) is the image of shape (band, nx, ny).

\[V = \Sigma^{-\frac{1}{2}} R x\]

where \(\Sigma\) refers to the inverse of the weights (i.e. the data covariance matrix when using natural weighting).

Parameters:

uvwdask.array.Array: uvw coordinates at which visibilities were obtained with shape (row, 3).
freqdask.array.Array: Observational frequencies of shape (chan,).
modeldask.array.Array: Model image to degrid of shape (nband, nx, ny).
freq_bin_idxdask.array.Array: Starting indices of frequency bins for each imaging band of shape (band,).
freq_bin_countsdask.array.Array: The number of channels in each imaging band of shape (band,).
cellfloat: The cell size of a pixel along the \(x\) direction in radians.
weightsdask.array.Array, optional: Imaging weights of shape (row, chan).
flag: :class:`dask.array.Array`, optional: Flags of shape (row,chan). Will only process visibilities for which flag!=0
cellyfloat, optional: The cell size of a pixel along the \(y\) direction in radians. By default same as cell size along \(x\) direction.
epsilonfloat, optional: The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.
nthreadsint, optional: The number of threads to use. Defaults to one. If set to zero will use all available cores.
do_wstackingbool, optional: Whether to correct for the w-term or not. Defaults to True

Returns:

visdask.array.Array: Visibilities corresponding to model of shape (row,chan).

africanus.gridding.wgridder.dask.residual(uvw, freq, image, vis, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]#

Compute residual image given a model and visibilities using ducc degridder i.e.

\[I^R = R^\dagger \Sigma^{-1}(V - Rx)\]

where \(R\) is an implicit degridding operator, \(V\) denotes visibilities of shape (row, chan) and \(x\) is the image of shape (band, nx, ny).

\[I^R = R^\dagger \Sigma^{-\frac{1}{2}}(\tilde{V} - \Sigma^{-\frac{1}{2}}Rx)\]

which is identical to the above expression if \(\tilde{V} = \Sigma^{-\frac{1}{2}}V\).

Parameters:

uvwdask.array.Array: uvw coordinates at which visibilities were obtained with shape (row, 3).
freqdask.array.Array: Observational frequencies of shape (chan,).
modeldask.array.Array: Model image to degrid of shape (band, nx, ny).
visdask.array.Array: Visibilities of shape (row,chan).
weightsdask.array.Array: Imaging weights of shape (row, chan).
freq_bin_idxdask.array.Array: Starting indices of frequency bins for each imaging band of shape (band,).
freq_bin_countsdask.array.Array: The number of channels in each imaging band of shape (band,).
cellfloat: The cell size of a pixel along the \(x\) direction in radians.
flag: :class:`dask.array.Array`, optional: Flags of shape (row,chan). Will only process visibilities for which flag!=0
cellyfloat, optional: The cell size of a pixel along the \(y\) direction in radians. By default same as cell size along \(x\) direction.
nuint, optional: The number of pixels in the padded grid along the \(x\) direction. Chosen automatically by default.
nvint, optional: The number of pixels in the padded grid along the \(y\) direction. Chosen automatically by default.
epsilonfloat, optional: The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.
nthreadsint, optional: The number of threads to use. Defaults to one.
do_wstackingbool, optional: Whether to correct for the w-term or not. Defaults to True
double_accumbool, optional: If true ducc will accumulate in double precision regardless of the input type.

Returns:

residualdask.array.Array: Residual image corresponding to model of shape (band, nx, ny).

africanus.gridding.wgridder.dask.hessian(uvw, freq, image, freq_bin_idx, freq_bin_counts, cell, weights=None, flag=None, celly=None, epsilon=1e-05, nthreads=1, do_wstacking=True, double_accum=False)[source]#

Compute action of Hessian on an image using ducc

\[R^\dagger \Sigma^{-1} R x\]

where \(R\) is an implicit degridding operator and \(x\) is the image of shape (band, nx, ny).

Parameters:

uvwdask.array.Array: uvw coordinates at which visibilities were obtained with shape (row, 3).
freqdask.array.Array: Observational frequencies of shape (chan,).
modeldask.array.Array: Model image to degrid of shape (band, nx, ny).
weightsdask.array.Array: Imaging weights of shape (row, chan).
freq_bin_idxdask.array.Array: Starting indices of frequency bins for each imaging band of shape (band,).
freq_bin_countsdask.array.Array: The number of channels in each imaging band of shape (band,).
cellfloat: The cell size of a pixel along the \(x\) direction in radians.
flag: :class:`dask.array.Array`, optional: Flags of shape (row,chan). Will only process visibilities for which flag!=0
cellyfloat, optional: The cell size of a pixel along the \(y\) direction in radians. By default same as cell size along \(x\) direction.
nuint, optional: The number of pixels in the padded grid along the \(x\) direction. Chosen automatically by default.
nvint, optional: The number of pixels in the padded grid along the \(y\) direction. Chosen automatically by default.
epsilonfloat, optional: The precision of the gridder with respect to the direct Fourier transform. By deafult, this is set to 1e-5 for single precision and 1e-7 for double precision.
nthreadsint, optional: The number of threads to use. Defaults to one.
do_wstackingbool, optional: Whether to correct for the w-term or not. Defaults to True
double_accumbool, optional: If true ducc will accumulate in double precision regardless of the input type.

Returns:

residualdask.array.Array: Residual image corresponding to model of shape (band, nx, ny).

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:

unumpy.ndarray or float: Maximum u coordinate in metres.
vnumpy.ndarray or float: Maximum v coordinate in metres.
wavelengthnumpy.ndarray or float: Wavelengths, in metres.
factorfloat, optional: Scaling factor
nyint, optional: Grid y dimension
nxint, optional: Grid x dimension

Returns:

numpy.ndarray: Cell size of u and v in arcseconds with shape (2,)

Raises:

ValueError: If the cell size criteria are not matched.