Welcome to Codex Africanus’s documentation!¶

LM coordinates of shape (source, 2) with L and M components in the last dimension.

uvw : numpy.ndarray

UVW coordinates of shape (row, 3) with U, V and W components in the last dimension.

frequency : numpy.ndarray

frequencies of shape (chan,)

convention : {‘fourier’, ‘casa’}

Uses the $e^{-2 \pi \mathit{i}}$ sign convention if fourier and $e^{2 \pi \mathit{i}}$ if casa.

Returns:

complex_phase : numpy.ndarray

complex of shape (source, row, chan)

Notes

Corresponds to the complex exponential of the Van Cittert-Zernike Theorem.

MeqTrees uses the CASA sign convention.

africanus.rime.parallactic_angles(times, antenna_positions, field_centre, backend='casa')[source]¶

Computes parallactic angles per timestep for the given reference antenna position and field centre.

Parameters:

times : numpy.ndarray

Array of Mean Julian Date times in seconds with shape (time,),

antenna_positions : numpy.ndarray

Antenna positions of shape (ant, 3) in metres in the ITRF frame.

field_centre : numpy.ndarray

Field centre of shape (2,) in radians

backend : {‘casa’, ‘test’}, optional

Backend to use for calculating the parallactic angles.

casa defers to an implementation depending on python-casacore. This backend should be used by default.

test creates parallactic angles by multiplying the times and antenna_position arrays. It exist solely for testing.

Returns:

parallactic_angles : numpy.ndarray

Parallactic angles of shape (time,ant)

africanus.rime.feed_rotation(parallactic_angles, feed_type='linear')[source]¶

Computes the 2x2 feed rotation (L) matrix from the parallactic_angles.

\[\begin{split}\textrm{linear} \begin{bmatrix} cos(pa) & sin(pa) \\ -sin(pa) & cos(pa) \end{bmatrix} \qquad \textrm{circular} \begin{bmatrix} e^{-i pa} & 0 \\ 0 & e^{i pa} \end{bmatrix}\end{split}\]

Parameters:

parallactic_angles : numpy.ndarray

floating point parallactic angles. Of shape (pa0, pa1, ..., pan).

feed_type : {‘linear’, ‘circular’}

The type of feed

Returns:

feed_matrix : numpy.ndarray

Feed rotation matrix of shape (pa0, pa1,...,pan,2,2)

africanus.rime.transform_sources(lm, parallactic_angles, pointing_errors, antenna_scaling, frequency, dtype=None)[source]¶

Creates beam sampling coordinates suitable for use in beam_cube_dde() by:

Rotating lm coordinates by the parallactic_angles
Adding pointing_errors
Scaling by antenna_scaling

Parameters:

LM coordinates of shape (src,2) in radians offset from the phase centre.

parallactic_angles : numpy.ndarray

parallactic angles of shape (time, antenna) in radians.

pointing_errors : numpy.ndarray

LM pointing errors for each antenna at each timestep in radians. Has shape (time, antenna, 2)

antenna_scaling : numpy.ndarray

antenna scaling factor for each channel and each antenna. Has shape (antenna, chan)

frequency : numpy.ndarray

frequencies for each channel. Has shape (chan,)

dtype : numpy.dtype, optional

Numpy dtype of result array. Should be float32 or float64. Defaults to float64

Returns:

coords : numpy.ndarray

coordinates of shape (3, src, time, antenna, chan) where each coordinate component represents l, m and frequency, respectively.

africanus.rime.beam_cube_dde(beam, beam_lm_extents, beam_freq_map, lm, parallactic_angles, point_errors, antenna_scaling, frequency)[source]¶

Evaluates Direction Dependent Effects along a source’s path by interpolating the values of a complex beam cube at the source location.

Parameters:

beam : numpy.ndarray

Complex beam cube of shape (beam_lw, beam_mh, beam_nud, corr, corr). beam_lw, beam_mh and beam_nud define the size of the cube in the l, m and frequency dimensions, respectively.

beam_lm_extents : numpy.ndarray

lm extents of the beam cube of shape (2, 2). [[lower_l, upper_l], [lower_m, upper_m]].

beam_freq_map : numpy.ndarray

Beam frequency map of shape (beam_nud,). This array is used to define interpolation along the (chan,) dimension.

Source lm coordinates of shape (source, 2). These coordinates are:

Scaled if the associated frequency lies outside the beam cube.

Offset by pointing errors: point_errors

Rotated by parallactic angles: parallactic_angles.

Scaled by antenna scaling factors: antenna_scaling.

parallactic_angles : numpy.ndarray

Parallactic angles of shape (time, ant).

point_errors : numpy.ndarray

Pointing errors of shape (time, ant, chan, 2).

antenna_scaling : numpy.ndarray

Antenna scaling factors of shape (ant, chan, 2)

frequency : numpy.ndarray

Frequencies of shape (chan,).

Returns:

ddes : numpy.ndarray

Direction Dependent Effects of shape (source, time, ant, chan, corr, corr)

Notes

Sources are clamped to the provided beam_lm_extents.
Frequencies outside the cube (i.e. outside beam_freq_map) introduce linear scaling to the lm coordinates of a source.

africanus.rime.zernike_dde(coords, coeffs, noll_index)[source]¶

Computes Direction Dependent Effects by evaluating Zernicke Polynomials defined by coefficients coeffs and noll indexes noll_index at the specified coordinates coords.

Decomposition of a voxel beam cube into Zernicke polynomial coefficients can be achieved through the use of the eidos package.

Parameters:

coords : numpy.ndarray

Float coordinates at which to evaluate the zernike polynomials. Has shape (3, source, time, ant, chan). The three components in the first dimension represent l, m and frequency coordinates, respectively.

coeffs : numpy.ndarray

complex Zernicke polynomial coefficients. Has shape (ant, chan, corr_1, ..., corr_n, poly) where poly is the number of polynomial coefficients and corr_1, ..., corr_n are a variable number of correlation dimensions.

noll_index : numpy.ndarray

Noll index associated with each polynomial coefficient. Has shape (ant, chan, corr_1, ..., corr_n, poly).

Returns:

dde : numpy.ndarray

complex values with shape (source, time, ant, chan, corr_1, ..., corr_n)

africanus.rime.wsclean_predict(uvw, lm, source_type, flux, coeffs, log_poly, ref_freq, gauss_shape, frequency)[source]¶

Predict visibilities from a WSClean sky model.

Parameters:

uvw : numpy.ndarray

UVW coordinates of shape (row, 3)

Source LM coordinates of shape (source, 2). Derived from the Ra and Dec fields.

source_type : numpy.ndarray

Strings defining the source type of shape (source,). Should be either "POINT" or "GAUSSIAN". Contains the Type field.

flux : numpy.ndarray

Source flux of shape (source,). Contains the I field.

coeffs : numpy.ndarray

Source Polynomial coefficients of shape (source, coeffs). Contains the SpectralIndex field.

log_poly : numpy.ndarray

Source polynomial type of shape (source,). If True, logarithmic polynomials are used. If False, standard polynomials are used. Contains the LogarithmicSI field.

ref_freq : numpy.ndarray

Source Reference frequency of shape (source,). Contains the ReferenceFrequency field.

gauss_shape : numpy.ndarray

Gaussian shape parameters of shape (source, 3) used when the corresponding source_type is "GAUSSIAN". The 3 components should contain the MajorAxis, MinorAxis and Orientation fields, respectively.

frequency : numpy.ndarray

Frequency of shape (chan,).

Returns:

visibilities : numpy.ndarray

Complex visibilities of shape (row, chan, 1)

Cuda¶

`predict_vis`(time_index, antenna1, antenna2)	Multiply Jones terms together to form model visibilities according to the following formula:
`phase_delay`(lm, uvw, frequency)	Computes the phase delay (K) term:
`feed_rotation`(parallactic_angles[, feed_type])	Computes the 2x2 feed rotation (L) matrix from the `parallactic_angles`.
`beam_cube_dde`(beam, beam_lm_ext, …)	Evaluates Direction Dependent Effects along a source’s path by interpolating the values of a complex beam cube at the source location.

africanus.rime.cuda.predict_vis(time_index, antenna1, antenna2, dde1_jones=None, source_coh=None, dde2_jones=None, die1_jones=None, base_vis=None, die2_jones=None)[source]¶

Multiply Jones terms together to form model visibilities according to the following formula:

\[V_{pq} = G_{p} \left( B_{pq} + \sum_{s} E_{ps} X_{pqs} E_{qs}^H \right) G_{q}^H\]

where for antenna $p$ and $q$, and source $s$:

$B_{{pq}}$ represent base coherencies.
$E_{{ps}}$ represents Direction-Dependent Jones terms.
$X_{{pqs}}$ represents a coherency matrix (per-source).
$G_{{p}}$ represents Direction-Independent Jones terms.

Generally, $E_{ps}$, $G_{p}$, $X_{pqs}$ should be formed by using the RIME API functions and combining them together with einsum().

Please read the Notes

Parameters:

time_index : cupy.ndarray

Time index used to look up the antenna Jones index for a particular baseline with shape (row,). Obtainable via cp.unique(time, return_inverse=True)[1].

antenna1 : cupy.ndarray

Antenna 1 index used to look up the antenna Jones for a particular baseline. with shape (row,).

antenna2 : cupy.ndarray

Antenna 2 index used to look up the antenna Jones for a particular baseline. with shape (row,).

dde1_jones : cupy.ndarray, optional

$E_{ps}$ Direction-Dependent Jones terms for the first antenna. shape (source,time,ant,chan,corr_1,corr_2)

source_coh : cupy.ndarray, optional

$X_{pqs}$ Direction-Dependent Coherency matrix for the baseline. with shape (source,row,chan,corr_1,corr_2)

dde2_jones : cupy.ndarray, optional

$E_{qs}$ Direction-Dependent Jones terms for the second antenna. This is usually the same array as dde1_jones as this preserves the symmetry of the RIME. predict_vis will perform the conjugate transpose internally. shape (source,time,ant,chan,corr_1,corr_2)

die1_jones : cupy.ndarray, optional

$G_{ps}$ Direction-Independent Jones terms for the first antenna of the baseline. with shape (time,ant,chan,corr_1,corr_2)

base_vis : cupy.ndarray, optional

$B_{pq}$ base coherencies, added to source coherency summation before multiplication with die1_jones and die2_jones. shape (row,chan,corr_1,corr_2).

die2_jones : cupy.ndarray, optional

$G_{ps}$ Direction-Independent Jones terms for the second antenna of the baseline. This is usually the same array as die1_jones as this preserves the symmetry of the RIME. predict_vis will perform the conjugate transpose internally. shape (time,ant,chan,corr_1,corr_2)

Returns:

visibilities : cupy.ndarray

Model visibilities of shape (row,chan,corr_1,corr_2)

Notes

Direction-Dependent terms (dde{1,2}_jones) and Independent (die{1,2}_jones) are optional, but if one is present, the other must be present.
The inputs to this function involve row, time and ant (antenna) dimensions.
Each row is associated with a pair of antenna Jones matrices at a particular timestep via the time_index, antenna1 and antenna2 inputs.
The row dimension must be an increasing partial order in time.

africanus.rime.cuda.phase_delay(lm, uvw, frequency)[source]¶

Computes the phase delay (K) term:

\[ \begin{align}\begin{aligned}& {\Large e^{-2 \pi i (u l + v m + w (n - 1))} }\\& \textrm{where } n = \sqrt{1 - l^2 - m^2}\end{aligned}\end{align} \]

Parameters:

lm : cupy.ndarray

LM coordinates of shape (source, 2) with L and M components in the last dimension.

uvw : cupy.ndarray

UVW coordinates of shape (row, 3) with U, V and W components in the last dimension.

frequency : cupy.ndarray

frequencies of shape (chan,)

convention : {‘fourier’, ‘casa’}

Uses the $e^{-2 \pi \mathit{i}}$ sign convention if fourier and $e^{2 \pi \mathit{i}}$ if casa.

Returns:

complex_phase : cupy.ndarray

complex of shape (source, row, chan)

Notes

Corresponds to the complex exponential of the Van Cittert-Zernike Theorem.

MeqTrees uses the CASA sign convention.

africanus.rime.cuda.feed_rotation(parallactic_angles, feed_type='linear')[source]¶

Computes the 2x2 feed rotation (L) matrix from the parallactic_angles.

\[\begin{split}\textrm{linear} \begin{bmatrix} cos(pa) & sin(pa) \\ -sin(pa) & cos(pa) \end{bmatrix} \qquad \textrm{circular} \begin{bmatrix} e^{-i pa} & 0 \\ 0 & e^{i pa} \end{bmatrix}\end{split}\]

Parameters:

parallactic_angles : cupy.ndarray

floating point parallactic angles. Of shape (pa0, pa1, ..., pan).

feed_type : {‘linear’, ‘circular’}

The type of feed

Returns:

feed_matrix : cupy.ndarray

Feed rotation matrix of shape (pa0, pa1,...,pan,2,2)

africanus.rime.cuda.beam_cube_dde(beam, beam_lm_ext, beam_freq_map, lm, parangles, pointing_errors, antenna_scaling, frequencies)[source]¶

Evaluates Direction Dependent Effects along a source’s path by interpolating the values of a complex beam cube at the source location.

Parameters:

beam : cupy.ndarray

Complex beam cube of shape (beam_lw, beam_mh, beam_nud, corr, corr). beam_lw, beam_mh and beam_nud define the size of the cube in the l, m and frequency dimensions, respectively.

beam_lm_extents : cupy.ndarray

lm extents of the beam cube of shape (2, 2). [[lower_l, upper_l], [lower_m, upper_m]].

beam_freq_map : cupy.ndarray

Beam frequency map of shape (beam_nud,). This array is used to define interpolation along the (chan,) dimension.

lm : cupy.ndarray

Source lm coordinates of shape (source, 2). These coordinates are:

Scaled if the associated frequency lies outside the beam cube.

Offset by pointing errors: point_errors

Rotated by parallactic angles: parallactic_angles.

Scaled by antenna scaling factors: antenna_scaling.

parallactic_angles : cupy.ndarray

Parallactic angles of shape (time, ant).

point_errors : cupy.ndarray

Pointing errors of shape (time, ant, chan, 2).

antenna_scaling : cupy.ndarray

Antenna scaling factors of shape (ant, chan, 2)

frequency : cupy.ndarray

Frequencies of shape (chan,).

Returns:

ddes : cupy.ndarray

Direction Dependent Effects of shape (source, time, ant, chan, corr, corr)

Notes

Sources are clamped to the provided beam_lm_extents.
Frequencies outside the cube (i.e. outside beam_freq_map) introduce linear scaling to the lm coordinates of a source.

Dask¶

`predict_vis`(time_index, antenna1, antenna2)	Multiply Jones terms together to form model visibilities according to the following formula:
`phase_delay`(lm, uvw, frequency[, convention])	Computes the phase delay (K) term:
`parallactic_angles`(times, antenna_positions, …)	Computes parallactic angles per timestep for the given reference antenna position and field centre.
`feed_rotation`(parallactic_angles, feed_type)	Computes the 2x2 feed rotation (L) matrix from the `parallactic_angles`.
`transform_sources`(lm, parallactic_angles, …)	Creates beam sampling coordinates suitable for use in `beam_cube_dde()` by:
`beam_cube_dde`(beam, beam_lm_extents, …)	Evaluates Direction Dependent Effects along a source’s path by interpolating the values of a complex beam cube at the source location.
`zernike_dde`(coords, coeffs, noll_index)	Computes Direction Dependent Effects by evaluating Zernicke Polynomials defined by coefficients `coeffs` and noll indexes `noll_index` at the specified coordinates `coords`.
`wsclean_predict`(uvw, lm, source_type, flux, …)	Predict visibilities from a WSClean sky model.

africanus.rime.dask.predict_vis(time_index, antenna1, antenna2, dde1_jones=None, source_coh=None, dde2_jones=None, die1_jones=None, base_vis=None, die2_jones=None, streams=None)[source]¶

Multiply Jones terms together to form model visibilities according to the following formula:

\[V_{pq} = G_{p} \left( B_{pq} + \sum_{s} E_{ps} X_{pqs} E_{qs}^H \right) G_{q}^H\]

where for antenna $p$ and $q$, and source $s$:

$B_{{pq}}$ represent base coherencies.
$E_{{ps}}$ represents Direction-Dependent Jones terms.
$X_{{pqs}}$ represents a coherency matrix (per-source).
$G_{{p}}$ represents Direction-Independent Jones terms.

Generally, $E_{ps}$, $G_{p}$, $X_{pqs}$ should be formed by using the RIME API functions and combining them together with einsum().

Please read the Notes

Parameters:

time_index : dask.array.Array

Time index used to look up the antenna Jones index for a particular baseline with shape (row,). Obtainable via time.map_blocks(lambda a: np.unique(a, return_inverse=True)[1]).

antenna1 : dask.array.Array

Antenna 1 index used to look up the antenna Jones for a particular baseline. with shape (row,).

antenna2 : dask.array.Array

Antenna 2 index used to look up the antenna Jones for a particular baseline. with shape (row,).

dde1_jones : dask.array.Array, optional

$E_{ps}$ Direction-Dependent Jones terms for the first antenna. shape (source,time,ant,chan,corr_1,corr_2)

source_coh : dask.array.Array, optional

$X_{pqs}$ Direction-Dependent Coherency matrix for the baseline. with shape (source,row,chan,corr_1,corr_2)

dde2_jones : dask.array.Array, optional

$E_{qs}$ Direction-Dependent Jones terms for the second antenna. This is usually the same array as dde1_jones as this preserves the symmetry of the RIME. predict_vis will perform the conjugate transpose internally. shape (source,time,ant,chan,corr_1,corr_2)

die1_jones : dask.array.Array, optional

$G_{ps}$ Direction-Independent Jones terms for the first antenna of the baseline. with shape (time,ant,chan,corr_1,corr_2)

base_vis : dask.array.Array, optional

$B_{pq}$ base coherencies, added to source coherency summation before multiplication with die1_jones and die2_jones. shape (row,chan,corr_1,corr_2).

die2_jones : dask.array.Array, optional

$G_{ps}$ Direction-Independent Jones terms for the second antenna of the baseline. This is usually the same array as die1_jones as this preserves the symmetry of the RIME. predict_vis will perform the conjugate transpose internally. shape (time,ant,chan,corr_1,corr_2)

streams : {False, True}

If True the coherencies are serially summed in a linear chain. If False, dask uses a tree style reduction algorithm.

Returns:

visibilities : dask.array.Array

Model visibilities of shape (row,chan,corr_1,corr_2)

Notes

Direction-Dependent terms (dde{1,2}_jones) and Independent (die{1,2}_jones) are optional, but if one is present, the other must be present.
The inputs to this function involve row, time and ant (antenna) dimensions.
Each row is associated with a pair of antenna Jones matrices at a particular timestep via the time_index, antenna1 and antenna2 inputs.
The row dimension must be an increasing partial order in time.
The ant dimension should only contain a single chunk equal to the number of antenna. Since each row can contain any antenna, random access must be preserved along this dimension.
The chunks in the row and time dimension must align. This subtle point must be understood otherwise invalid results will be produced by the chunking scheme. In the example below we have four unique time indices [0,1,2,3], and four unique antenna [0,1,2,3] indexing 10 rows.
```
#  Row indices into the time/antenna indexed arrays
time_idx = np.asarray([0,0,1,1,2,2,2,2,3,3])
ant1 = np.asarray(    [0,0,0,0,1,1,1,2,2,3]
ant2 = np.asarray(    [0,1,2,3,1,2,3,2,3,3])
```
A reasonable chunking scheme for the row and time dimension would be (4,4,2) and (2,1,1) respectively. Another way of explaining this is that the first four rows contain two unique timesteps, the second four rows contain one unique timestep and the last two rows contain one unique timestep.

Some rules of thumb:
1. The number chunks in row and time must match although the individual chunk sizes need not.
2. Unique timesteps should not be split across row chunks.
3. For a Measurement Set whose rows are ordered on the TIME column, the following is a good way of obtaining the row chunking strategy:
```
import numpy as np
import pyrap.tables as pt

ms = pt.table("data.ms")
times = ms.getcol("TIME")
unique_times, chunks = np.unique(times, return_counts=True)
```
4. Use aggregate_chunks() to aggregate multiple row and time chunks into chunks large enough such that functions operating on the resulting data can drop the GIL and spend time processing the data. Expanding the previous example:
```
# Aggregate row
utimes = unique_times.size
# Single chunk for each unique time
time_chunks = (1,)*utimes
# Aggregate row chunks into chunks <= 10000
aggregate_chunks((chunks, time_chunks), (10000, utimes))
```

africanus.rime.dask.phase_delay(lm, uvw, frequency, convention='fourier')[source]¶

Computes the phase delay (K) term:

\[ \begin{align}\begin{aligned}& {\Large e^{-2 \pi i (u l + v m + w (n - 1))} }\\& \textrm{where } n = \sqrt{1 - l^2 - m^2}\end{aligned}\end{align} \]

Parameters:

LM coordinates of shape (source, 2) with L and M components in the last dimension.

uvw : dask.array.Array

UVW coordinates of shape (row, 3) with U, V and W components in the last dimension.

frequency : dask.array.Array

frequencies of shape (chan,)

convention : {‘fourier’, ‘casa’}

Uses the $e^{-2 \pi \mathit{i}}$ sign convention if fourier and $e^{2 \pi \mathit{i}}$ if casa.

Returns:

complex_phase : dask.array.Array

complex of shape (source, row, chan)

Notes

Corresponds to the complex exponential of the Van Cittert-Zernike Theorem.

MeqTrees uses the CASA sign convention.

africanus.rime.dask.parallactic_angles(times, antenna_positions, field_centre, **kwargs)[source]¶

Computes parallactic angles per timestep for the given reference antenna position and field centre.

Parameters:

times : dask.array.Array

Array of Mean Julian Date times in seconds with shape (time,),

antenna_positions : dask.array.Array

Antenna positions of shape (ant, 3) in metres in the ITRF frame.

field_centre : dask.array.Array

Field centre of shape (2,) in radians

backend : {‘casa’, ‘test’}, optional

Backend to use for calculating the parallactic angles.

casa defers to an implementation depending on python-casacore. This backend should be used by default.

test creates parallactic angles by multiplying the times and antenna_position arrays. It exist solely for testing.

Returns:

parallactic_angles : dask.array.Array

Parallactic angles of shape (time,ant)

africanus.rime.dask.feed_rotation(parallactic_angles, feed_type)[source]¶

Computes the 2x2 feed rotation (L) matrix from the parallactic_angles.

\[\begin{split}\textrm{linear} \begin{bmatrix} cos(pa) & sin(pa) \\ -sin(pa) & cos(pa) \end{bmatrix} \qquad \textrm{circular} \begin{bmatrix} e^{-i pa} & 0 \\ 0 & e^{i pa} \end{bmatrix}\end{split}\]

Parameters:

parallactic_angles : numpy.ndarray

floating point parallactic angles. Of shape (pa0, pa1, ..., pan).

feed_type : {‘linear’, ‘circular’}

The type of feed

Returns:

feed_matrix : numpy.ndarray

Feed rotation matrix of shape (pa0, pa1,...,pan,2,2)

africanus.rime.dask.transform_sources(lm, parallactic_angles, pointing_errors, antenna_scaling, frequency, dtype=None)[source]¶

Creates beam sampling coordinates suitable for use in beam_cube_dde() by:

Rotating lm coordinates by the parallactic_angles
Adding pointing_errors
Scaling by antenna_scaling

Parameters:

LM coordinates of shape (src,2) in radians offset from the phase centre.

parallactic_angles : dask.array.Array

parallactic angles of shape (time, antenna) in radians.

pointing_errors : dask.array.Array

LM pointing errors for each antenna at each timestep in radians. Has shape (time, antenna, 2)

antenna_scaling : dask.array.Array

antenna scaling factor for each channel and each antenna. Has shape (antenna, chan)

frequency : dask.array.Array

frequencies for each channel. Has shape (chan,)

dtype : numpy.dtype, optional

Numpy dtype of result array. Should be float32 or float64. Defaults to float64

Returns:

coords : dask.array.Array

coordinates of shape (3, src, time, antenna, chan) where each coordinate component represents l, m and frequency, respectively.

africanus.rime.dask.beam_cube_dde(beam, beam_lm_extents, beam_freq_map, lm, parallactic_angles, point_errors, antenna_scaling, frequencies)[source]¶

Evaluates Direction Dependent Effects along a source’s path by interpolating the values of a complex beam cube at the source location.

Parameters:

beam : dask.array.Array

Complex beam cube of shape (beam_lw, beam_mh, beam_nud, corr, corr). beam_lw, beam_mh and beam_nud define the size of the cube in the l, m and frequency dimensions, respectively.

beam_lm_extents : dask.array.Array

lm extents of the beam cube of shape (2, 2). [[lower_l, upper_l], [lower_m, upper_m]].

beam_freq_map : dask.array.Array

Beam frequency map of shape (beam_nud,). This array is used to define interpolation along the (chan,) dimension.

Source lm coordinates of shape (source, 2). These coordinates are:

Scaled if the associated frequency lies outside the beam cube.

Offset by pointing errors: point_errors

Rotated by parallactic angles: parallactic_angles.

Scaled by antenna scaling factors: antenna_scaling.

parallactic_angles : dask.array.Array

Parallactic angles of shape (time, ant).

point_errors : dask.array.Array

Pointing errors of shape (time, ant, chan, 2).

antenna_scaling : dask.array.Array

Antenna scaling factors of shape (ant, chan, 2)

frequency : dask.array.Array

Frequencies of shape (chan,).

Returns:

ddes : dask.array.Array

Direction Dependent Effects of shape (source, time, ant, chan, corr, corr)

Notes

Sources are clamped to the provided beam_lm_extents.
Frequencies outside the cube (i.e. outside beam_freq_map) introduce linear scaling to the lm coordinates of a source.

africanus.rime.dask.zernike_dde(coords, coeffs, noll_index)[source]¶

Computes Direction Dependent Effects by evaluating Zernicke Polynomials defined by coefficients coeffs and noll indexes noll_index at the specified coordinates coords.

Decomposition of a voxel beam cube into Zernicke polynomial coefficients can be achieved through the use of the eidos package.

Parameters:

coords : dask.array.Array

Float coordinates at which to evaluate the zernike polynomials. Has shape (3, source, time, ant, chan). The three components in the first dimension represent l, m and frequency coordinates, respectively.

coeffs : dask.array.Array

complex Zernicke polynomial coefficients. Has shape (ant, chan, corr_1, ..., corr_n, poly) where poly is the number of polynomial coefficients and corr_1, ..., corr_n are a variable number of correlation dimensions.

noll_index : dask.array.Array

Noll index associated with each polynomial coefficient. Has shape (ant, chan, corr_1, ..., corr_n, poly).

Returns:

dde : dask.array.Array

complex values with shape (source, time, ant, chan, corr_1, ..., corr_n)

africanus.rime.dask.wsclean_predict(uvw, lm, source_type, flux, coeffs, log_poly, ref_freq, gauss_shape, frequency)[source]¶

Predict visibilities from a WSClean sky model.

Parameters:

uvw : dask.array.Array

UVW coordinates of shape (row, 3)

Source LM coordinates of shape (source, 2). Derived from the Ra and Dec fields.

source_type : dask.array.Array

Strings defining the source type of shape (source,). Should be either "POINT" or "GAUSSIAN". Contains the Type field.

flux : dask.array.Array

Source flux of shape (source,). Contains the I field.

coeffs : dask.array.Array

Source Polynomial coefficients of shape (source, coeffs). Contains the SpectralIndex field.

log_poly : dask.array.Array

Source polynomial type of shape (source,). If True, logarithmic polynomials are used. If False, standard polynomials are used. Contains the LogarithmicSI field.

ref_freq : dask.array.Array

Source Reference frequency of shape (source,). Contains the ReferenceFrequency field.

gauss_shape : dask.array.Array

Gaussian shape parameters of shape (source, 3) used when the corresponding source_type is "GAUSSIAN". The 3 components should contain the MajorAxis, MinorAxis and Orientation fields, respectively.

frequency : dask.array.Array

Frequency of shape (chan,).

Returns:

visibilities : dask.array.Array

Complex visibilities of shape (row, chan, 1)

Direct Fourier Transform¶

Functions used to compute the discretised direct Fourier transform (DFT) for an ideal interferometer. The DFT for an ideal interferometer is defined as

\[V(u,v,w) = \int B(l,m) e^{-2\pi i \left( ul + vm + w(n-1)\right)} \frac{dl dm}{n}\]

where $u,v,w$ are data space coordinates and where visibilities $V$ have been obtained. The $l,m,n$ are signal space coordinates at which we wish to reconstruct the signal $B$. Note that the signal correspondes to the brightness matrix and not the Stokes parameters. We adopt the convention where we absorb the fixed coordinate $n$ in the denominator into the image. Note that the data space coordinates have an implicit dependence on frequency and time and that the image has an implicit dependence on frequency. The discretised form of the DFT can be written as

\[V(u,v,w) = \sum_s e^{-2 \pi i (u l_s + v m_s + w (n_s - 1))} \cdot B_s\]

where $s$ labels the source (or pixel) location. If only a single correlation is present $B = I$, this can be cast into a matrix equation as follows

\[V = R I\]

where $R$ is the operator that maps an image to visibility space. This mapping is implemented by the im_to_vis() function. If multiple correlations are present then each one is mapped to its corresponding visibility. An imaging algorithm also requires the adjoint denoted $R^\dagger$ which is simply the complex conjugate transpose of $R$. The dirty image is obtained by applying the adjoint operator to the visibilities

\[I^D = R^\dagger V\]

This is implemented by the vis_to_im() function. Note that an imaging algorithm using these operators will actually reconstruct $\frac{I}{n}$ but that it is trivial to obtain $I$ since $n$ is known at each location in the image.

Numpy¶

`im_to_vis`(image, uvw, lm, frequency[, …])	Computes the discrete image to visibility mapping of an ideal interferometer:
`vis_to_im`(vis, uvw, lm, frequency, flags[, …])	Computes visibility to image mapping of an ideal interferometer:

africanus.dft.im_to_vis(image, uvw, lm, frequency, convention='fourier', dtype=None)[source]¶

Computes the discrete image to visibility mapping of an ideal interferometer:

\[{\Large \sum_s e^{-2 \pi i (u l_s + v m_s + w (n_s - 1))} \cdot I_s }\]

Parameters:

image : numpy.ndarray

image of shape (source, chan, corr) The brighness matrix in each pixel (flatten 2D array per channel and corr). Note not Stokes terms

uvw : numpy.ndarray

uvw coordinates of shape (row, 3) with u, v and w components in the last dimension.

lm coordinates of shape (source, 2) with l and m components in the last dimension.

frequency : numpy.ndarray

frequencies of shape (chan,)

convention : {‘fourier’, ‘casa’}

Uses the $e^{-2 \pi \mathit{i}}$ sign convention if fourier and $e^{2 \pi \mathit{i}}$ if casa.

dtype : np.dtype, optional

Datatype of result. Should be either np.complex64 or np.complex128. If None, numpy.result_type() is used to infer the data type from the inputs.

Returns:

visibilties : numpy.ndarray

complex of shape (row, chan, corr)

africanus.dft.vis_to_im(vis, uvw, lm, frequency, flags, convention='fourier', dtype=None)[source]¶

Computes visibility to image mapping of an ideal interferometer:

\[{\Large \sum_k e^{ 2 \pi i (u_k l + v_k m + w_k (n - 1))} \cdot V_k}\]

Parameters:

vis : numpy.ndarray

visibilities of shape (row, chan, corr) Visibilities corresponding to brightness terms. Note the dirty images produced do not necessarily correspond to Stokes terms and need to be converted.

uvw : numpy.ndarray

uvw coordinates of shape (row, 3) with u, v and w components in the last dimension.

lm coordinates of shape (source, 2) with l and m components in the last dimension.

frequency : numpy.ndarray

frequencies of shape (chan,)

flags : numpy.ndarray

Boolean array of shape (row, chan, corr) Note that if one correlation is flagged we discard all of them otherwise we end up irretrievably mixing Stokes terms.

convention : {‘fourier’, ‘casa’}

Uses the $e^{-2 \pi \mathit{i}}$ sign convention if fourier and $e^{2 \pi \mathit{i}}$ if casa.

dtype : np.dtype, optional

Datatype of result. Should be either np.float32 or np.float64. If None, numpy.result_type() is used to infer the data type from the inputs.

Returns:

image : numpy.ndarray

float of shape (source, chan, corr)

Dask¶

`im_to_vis`(image, uvw, lm, frequency[, …])	Computes the discrete image to visibility mapping of an ideal interferometer:
`vis_to_im`(vis, uvw, lm, frequency, flags[, …])	Computes visibility to image mapping of an ideal interferometer:

africanus.dft.dask.im_to_vis(image, uvw, lm, frequency, convention='fourier', dtype=<MagicMock id='140699284538088'>)[source]¶

Computes the discrete image to visibility mapping of an ideal interferometer:

\[{\Large \sum_s e^{-2 \pi i (u l_s + v m_s + w (n_s - 1))} \cdot I_s }\]

Parameters:

image : dask.array.Array

image of shape (source, chan, corr) The brighness matrix in each pixel (flatten 2D array per channel and corr). Note not Stokes terms

uvw : dask.array.Array

uvw coordinates of shape (row, 3) with u, v and w components in the last dimension.

lm coordinates of shape (source, 2) with l and m components in the last dimension.

frequency : dask.array.Array

frequencies of shape (chan,)

convention : {‘fourier’, ‘casa’}

Uses the $e^{-2 \pi \mathit{i}}$ sign convention if fourier and $e^{2 \pi \mathit{i}}$ if casa.

dtype : np.dtype, optional

Datatype of result. Should be either np.complex64 or np.complex128. If None, numpy.result_type() is used to infer the data type from the inputs.

Returns:

visibilties : dask.array.Array

complex of shape (row, chan, corr)

africanus.dft.dask.vis_to_im(vis, uvw, lm, frequency, flags, convention='fourier', dtype=<MagicMock id='140699286029816'>)[source]¶

Computes visibility to image mapping of an ideal interferometer:

\[{\Large \sum_k e^{ 2 \pi i (u_k l + v_k m + w_k (n - 1))} \cdot V_k}\]

Parameters:

vis : dask.array.Array

visibilities of shape (row, chan, corr) Visibilities corresponding to brightness terms. Note the dirty images produced do not necessarily correspond to Stokes terms and need to be converted.

uvw : dask.array.Array

uvw coordinates of shape (row, 3) with u, v and w components in the last dimension.

lm coordinates of shape (source, 2) with l and m components in the last dimension.

frequency : dask.array.Array

frequencies of shape (chan,)

flags : dask.array.Array

Boolean array of shape (row, chan, corr) Note that if one correlation is flagged we discard all of them otherwise we end up irretrievably mixing Stokes terms.

convention : {‘fourier’, ‘casa’}

Uses the $e^{-2 \pi \mathit{i}}$ sign convention if fourier and $e^{2 \pi \mathit{i}}$ if casa.

dtype : np.dtype, optional

Datatype of result. Should be either np.float32 or np.float64. If None, numpy.result_type() is used to infer the data type from the inputs.

Returns:

image : dask.array.Array

float of shape (source, chan, corr)

Gridding and Degridding¶

This section contains routines for

Gridding complex visibilities onto an image.
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 of shape (row, chan, corr_1, corr_2). 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=<MagicMock id='140699286834984'>)[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 of shape (row, chan, corr_1, corr_2). 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 of shape (row, chan, corr_1, corr_2). 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 of shape (row, chan, corr_1, corr_2). 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

Nifty¶

Dask wrappers around Nifty’s Gridder.

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:

nx : int, optional

Number of X pixels in the grid. Defaults to 1024.

ny : int, optional

Number of Y pixels in the grid. Defaults to 1024.

cell_size_x : float, optional

Cell size of the X pixel in arcseconds. Defaults to 2.0.

cell_size_y : float, optional

Cell size of the Y pixel in arcseconds. Defaults to 2.0.

eps : float

Gridder accuracy error. Defaults to 2e-13

Returns:

grid_config : GridderConfigWrapper

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:

vis : dask.array.Array

visibilities of shape (row, chan, corr)

uvw : dask.array.Array

uvw coordinates of shape (row, 3)

flags : dask.array.Array

flags of shape (row, chan, corr)

weights : dask.array.Array

weights of shape (row, chan, corr).

frequencies : dask.array.Array

frequencies of shape (chan,)

grid_config : GridderConfigWrapper

Gridding Configuration

wmin : float

Minimum W coordinate to grid. Defaults to -1e30.

wmax : float

Maximum W coordinate to grid. Default to 1e30.

streams : int, optional

Number of parallel gridding operations. Default to None, in which case as many grids as visibility chunks will be created.

Returns:

grid : dask.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:

grid : dask.array.Array

Gridded visibilities of shape (nv, nu, ncorr)

grid_config : GridderConfigWrapper

Gridding configuration

Returns:

dirty : dask.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:

grid : dask.array.Array

gridded visibilities of shape (ny, nx, corr)

uvw : dask.array.Array

uvw coordinates of shape (row, 3)

flags : dask.array.Array

flags of shape (row, chan, corr)

weights : dask.array.Array

weights of shape (row, chan, corr). Currently unsupported and ignored.

frequencies : dask.array.Array

frequencies of shape (chan,)

grid_config : GridderConfigWrapper

Gridding Configuration

wmin : float

Minimum W coordinate to grid. Defaults to -1e30.

wmax : float

Maximum W coordinate to grid. Default to 1e30.

Returns:

grid : dask.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:

image : dask.array.Array

Image of shape (ny, nx, corr).

grid_config : GridderConfigWrapper

nifty gridding configuration object

Returns:

model_vis : dask.array.Array

Model visibilities of shape (nu, nv, corr).

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:

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

Raises:

ValueError

If the cell size criteria are not matched.

Convolution Filters¶

Convolution filters suitable for use in gridding and degridding.

API¶

convolution_filter(half_support, …) Create a 2D Convolution Filter suitable for use with gridding and degridding functions.

africanus.filters.convolution_filter(half_support, oversampling_factor, filter_type, **kwargs)[source]¶

Create a 2D Convolution Filter suitable for use with gridding and degridding functions.

Parameters:

half_support : integer

Half support (N) of the filter. The filter has a full support of N*2 + 3 taps. Two of the taps exist as padding.

oversampling_factor : integer

Number of spaces in-between grid-steps (improves gridding/degridding accuracy)

filter_type : {‘kaiser-bessel’, ‘sinc’}

Filter type. See Convolution Filters for further information.

beta : float, optional

Beta shape parameter for Kaiser Bessel filters.

normalise : {True, False}

Normalise the filter by the it’s volume. Defaults to True.

Returns:

ConvolutionFilter

namedtuple containing filter attributes

africanus.filters.ConvolutionFilter(half_sup, oversample, full_sup_wo_padding, full_sup, no_taps, filter_taps) = <class 'africanus.filters.conv_filters.ConvolutionFilter'>¶

Kaiser Bessel¶

The Kaiser Bessel function.

`kaiser_bessel`(u, W, beta)	Compute a 1D Kaiser Bessel filter as defined in Selection of a Convolution Function for Fourier Inversion Using Gridding.
`kaiser_bessel_with_sinc`(u, W, oversample, beta)	Produces a filter composed of Kaiser Bessel multiplied by a sinc.
`kaiser_bessel_fourier`(x, W, beta)	Computes the Fourier Transform of a 1D Kaiser Bessel filter.
`estimate_kaiser_bessel_beta`(W)	Estimate the kaiser bessel beta using the following heuristic:

africanus.filters.kaiser_bessel_filter.kaiser_bessel(u, W, beta)[source]¶

Compute a 1D Kaiser Bessel filter as defined in Selection of a Convolution Function for Fourier Inversion Using Gridding.

Parameters:

u : numpy.ndarray

Filter positions

W : int

Width of the filter

beta : float, optional

Kaiser Bessel shape parameter

Returns:

Kaiser Bessel filter with the same shape as u

africanus.filters.kaiser_bessel_filter.kaiser_bessel_with_sinc(u, W, oversample, beta, normalise=True)[source]¶

Produces a filter composed of Kaiser Bessel multiplied by a sinc.

Accounts for the oversampling factor, as well as normalising the filter.

Parameters:

u : numpy.ndarray

Filter positions

W : int

Width of the filter

oversample : int

Oversampling factor

beta : float

Kaiser Bessel shape parameter

normalise : optional, {True, False}

True if the filter should be normalised

Returns:

Filter with the same shape as u

africanus.filters.kaiser_bessel_filter.kaiser_bessel_fourier(x, W, beta)[source]¶

Computes the Fourier Transform of a 1D Kaiser Bessel filter. as defined in Selection of a Convolution Function for Fourier Inversion Using Gridding.

Parameters:

Filter positions

W : int

Width of the filter.

beta : float

Kaiser bessel shape parameter

Returns:

Fourier Transform of the Kaiser Bessel, with the same shape as x.

africanus.filters.kaiser_bessel_filter.estimate_kaiser_bessel_beta(W)[source]¶

Estimate the kaiser bessel beta using the following heuristic:

\[\beta = 2.34 \times W\]

Derived from Nonuniform fast Fourier transforms using min-max interpolation.

Parameters:

W : int

Width of the filter

Returns:

float

Kaiser Bessel beta shape parameter

Sinc¶

The Sinc function.

Deconvolution Algorithms¶

africanus.deconv.hogbom.hogbom_clean(dirty, psf, gamma=0.1, threshold='default', niter='default')[source]¶

Performs Hogbom Clean on the dirty image given the psf.

Parameters:

dirty : np.ndarray

float64 dirty image of shape (ny, nx)

psf : np.ndarray

float64 Point Spread Function of shape (2*ny, 2*nx)

gamma (optional) float

the gain factor (must be less than one)

threshold (optional) : float or str

the threshold to clean to

niter (optional : integer

the maximum number of iterations allowed

Returns:

np.ndarray

float64 clean image of shape (ny, nx)

np.ndarray

float64 residual image of shape (ny, nx)

Coordinate Transforms¶

Numpy¶

`radec_to_lm`(radec[, phase_centre])	Converts Right-Ascension/Declination coordinates in radians to a Direction Cosine lm coordinates, relative to the Phase Centre.
`radec_to_lmn`(radec[, phase_centre])	Converts Right-Ascension/Declination coordinates in radians to a Direction Cosine lm coordinates, relative to the Phase Centre.
`lm_to_radec`(lm[, phase_centre])	Convert Direction Cosine lm coordinates to Right Ascension/Declination coordinates in radians, relative to the Phase Centre.
`lmn_to_radec`(lmn[, phase_centre])	Convert Direction Cosine lm coordinates to Right Ascension/Declination coordinates in radians, relative to the Phase Centre.

africanus.coordinates.radec_to_lm(radec, phase_centre=None)[source]¶

Converts Right-Ascension/Declination coordinates in radians to a Direction Cosine lm coordinates, relative to the Phase Centre.

\begin{eqnarray} & l =& \, \cos \, \delta \sin \, \Delta \alpha \\ & m =& \, \sin \, \delta \cos \, \delta 0 - \cos \delta \sin \delta 0 \cos \Delta \alpha \\ & n =& \, \sqrt{1 - l^2 - m^2} - 1 \end{eqnarray}

where $\Delta \alpha = \alpha - \alpha 0$ is the difference between the Right Ascension of each coordinate and the phase centre and $\delta 0$ is the Declination of the phase centre.

Parameters:

radec : numpy.ndarray

radec coordinates of shape (coord, 2) where Right-Ascension and Declination are in the last 2 components, respectively.

phase_centre : numpy.ndarray, optional

radec coordinates of the Phase Centre. Shape (2,)

Returns:

lm Direction Cosines of shape (coord, 2)

africanus.coordinates.radec_to_lmn(radec, phase_centre=None)[source]¶

Converts Right-Ascension/Declination coordinates in radians to a Direction Cosine lm coordinates, relative to the Phase Centre.

\begin{eqnarray} & l =& \, \cos \, \delta \sin \, \Delta \alpha \\ & m =& \, \sin \, \delta \cos \, \delta 0 - \cos \delta \sin \delta 0 \cos \Delta \alpha \\ & n =& \, \sqrt{1 - l^2 - m^2} - 1 \end{eqnarray}

where $\Delta \alpha = \alpha - \alpha 0$ is the difference between the Right Ascension of each coordinate and the phase centre and $\delta 0$ is the Declination of the phase centre.

Parameters:

radec : numpy.ndarray

radec coordinates of shape (coord, 2) where Right-Ascension and Declination are in the last 2 components, respectively.

phase_centre : numpy.ndarray, optional

radec coordinates of the Phase Centre. Shape (2,)

Returns:

lm Direction Cosines of shape (coord, 3)

africanus.coordinates.lm_to_radec(lm, phase_centre=None)[source]¶

Convert Direction Cosine lm coordinates to Right Ascension/Declination coordinates in radians, relative to the Phase Centre.

\begin{eqnarray} & \delta = & \, \arcsin \left( m \cos \delta 0 + n \sin \delta 0 \right) \\ & \alpha = & \, \arctan \left( \frac{l}{n \cos \delta 0 - m \sin \delta 0} \right) \\ \end{eqnarray}

where $\alpha$ is the Right Ascension of each coordinate and the phase centre and $\delta 0$ is the Declination of the phase centre.

Parameters:

lm Direction Cosines of shape (coord, 2)

phase_centre : numpy.ndarray, optional

radec coordinates of the Phase Centre. Shape (2,)

Returns:

radec coordinates of shape (coord, 2) where Right-Ascension and Declination are in the last 2 components, respectively.

africanus.coordinates.lmn_to_radec(lmn, phase_centre=None)[source]¶

Convert Direction Cosine lm coordinates to Right Ascension/Declination coordinates in radians, relative to the Phase Centre.

\begin{eqnarray} & \delta = & \, \arcsin \left( m \cos \delta 0 + n \sin \delta 0 \right) \\ & \alpha = & \, \arctan \left( \frac{l}{n \cos \delta 0 - m \sin \delta 0} \right) \\ \end{eqnarray}

where $\alpha$ is the Right Ascension of each coordinate and the phase centre and $\delta 0$ is the Declination of the phase centre.

Parameters:

lmn : numpy.ndarray

lm Direction Cosines of shape (coord, 3)

phase_centre : numpy.ndarray, optional

radec coordinates of the Phase Centre. Shape (2,)

Returns:

radec coordinates of shape (coord, 2) where Right-Ascension and Declination are in the last 2 components, respectively.

Dask¶

`radec_to_lm`(radec[, phase_centre])	Converts Right-Ascension/Declination coordinates in radians to a Direction Cosine lm coordinates, relative to the Phase Centre.
`radec_to_lmn`(radec[, phase_centre])	Converts Right-Ascension/Declination coordinates in radians to a Direction Cosine lm coordinates, relative to the Phase Centre.
`lm_to_radec`(lm[, phase_centre])	Convert Direction Cosine lm coordinates to Right Ascension/Declination coordinates in radians, relative to the Phase Centre.
`lmn_to_radec`(lmn[, phase_centre])	Convert Direction Cosine lm coordinates to Right Ascension/Declination coordinates in radians, relative to the Phase Centre.

africanus.coordinates.dask.radec_to_lm(radec, phase_centre=None)[source]¶

Converts Right-Ascension/Declination coordinates in radians to a Direction Cosine lm coordinates, relative to the Phase Centre.

\begin{eqnarray} & l =& \, \cos \, \delta \sin \, \Delta \alpha \\ & m =& \, \sin \, \delta \cos \, \delta 0 - \cos \delta \sin \delta 0 \cos \Delta \alpha \\ & n =& \, \sqrt{1 - l^2 - m^2} - 1 \end{eqnarray}

where $\Delta \alpha = \alpha - \alpha 0$ is the difference between the Right Ascension of each coordinate and the phase centre and $\delta 0$ is the Declination of the phase centre.

Parameters:

radec : dask.array.Array

radec coordinates of shape (coord, 2) where Right-Ascension and Declination are in the last 2 components, respectively.

phase_centre : dask.array.Array, optional

radec coordinates of the Phase Centre. Shape (2,)

Returns:

lm Direction Cosines of shape (coord, 2)

africanus.coordinates.dask.radec_to_lmn(radec, phase_centre=None)[source]¶

Converts Right-Ascension/Declination coordinates in radians to a Direction Cosine lm coordinates, relative to the Phase Centre.

\begin{eqnarray} & l =& \, \cos \, \delta \sin \, \Delta \alpha \\ & m =& \, \sin \, \delta \cos \, \delta 0 - \cos \delta \sin \delta 0 \cos \Delta \alpha \\ & n =& \, \sqrt{1 - l^2 - m^2} - 1 \end{eqnarray}

where $\Delta \alpha = \alpha - \alpha 0$ is the difference between the Right Ascension of each coordinate and the phase centre and $\delta 0$ is the Declination of the phase centre.

Parameters:

radec : dask.array.Array

radec coordinates of shape (coord, 2) where Right-Ascension and Declination are in the last 2 components, respectively.

phase_centre : dask.array.Array, optional

radec coordinates of the Phase Centre. Shape (2,)

Returns:

lm Direction Cosines of shape (coord, 3)

africanus.coordinates.dask.lm_to_radec(lm, phase_centre=None)[source]¶

Convert Direction Cosine lm coordinates to Right Ascension/Declination coordinates in radians, relative to the Phase Centre.

\begin{eqnarray} & \delta = & \, \arcsin \left( m \cos \delta 0 + n \sin \delta 0 \right) \\ & \alpha = & \, \arctan \left( \frac{l}{n \cos \delta 0 - m \sin \delta 0} \right) \\ \end{eqnarray}

where $\alpha$ is the Right Ascension of each coordinate and the phase centre and $\delta 0$ is the Declination of the phase centre.

Parameters:

lm Direction Cosines of shape (coord, 2)

phase_centre : dask.array.Array, optional

radec coordinates of the Phase Centre. Shape (2,)

Returns:

radec coordinates of shape (coord, 2) where Right-Ascension and Declination are in the last 2 components, respectively.

africanus.coordinates.dask.lmn_to_radec(lmn, phase_centre=None)[source]¶

Convert Direction Cosine lm coordinates to Right Ascension/Declination coordinates in radians, relative to the Phase Centre.

\begin{eqnarray} & \delta = & \, \arcsin \left( m \cos \delta 0 + n \sin \delta 0 \right) \\ & \alpha = & \, \arctan \left( \frac{l}{n \cos \delta 0 - m \sin \delta 0} \right) \\ \end{eqnarray}

where $\alpha$ is the Right Ascension of each coordinate and the phase centre and $\delta 0$ is the Declination of the phase centre.

Parameters:

lmn : dask.array.Array

lm Direction Cosines of shape (coord, 3)

phase_centre : dask.array.Array, optional

radec coordinates of the Phase Centre. Shape (2,)

Returns:

radec coordinates of shape (coord, 2) where Right-Ascension and Declination are in the last 2 components, respectively.

Sky Model¶

Functionality related to the Sky Model.

Coherency Conversion¶

Utilities for converting back and forth between stokes parameters and correlations

Numpy¶

convert(input, input_schema, output_schema) This function converts forward and backward from stokes I,Q,U,V to both linear XX,XY,YX,YY and circular RR, RL, LR, LL correlations.

africanus.model.coherency.convert(input, input_schema, output_schema)[source]¶

This function converts forward and backward from stokes I,Q,U,V to both linear XX,XY,YX,YY and circular RR, RL, LR, LL correlations.

For example, we can convert from stokes parameters to linear correlations:

stokes.shape == (10, 4, 4)
corrs = convert(stokes, ["I", "Q", "U", "V"],
                [['XX', 'XY'], ['YX', 'YY'])

assert corrs.shape == (10, 4, 2, 2)

Or circular correlations to stokes:

vis.shape == (10, 4, 2, 2)

stokes = convert(vis, [['RR', 'RL'], ['LR', 'LL']],
                        ['I', 'Q', 'U', 'V'])

assert stokes.shape == (10, 4, 4)

input can output can be arbitrarily nested or ordered lists, but the appropriate inputs must be present to produce the requested outputs.

The elements of input and output may be strings or integers representing stokes parameters or correlations. See the Notes for a full list.

Parameters:

input : numpy.ndarray

Complex or floating point input data of shape (dim_1, ..., dim_n, icorr_1, ..., icorr_m)

input_schema : list of str or int

A schema describing the icorr_1, ..., icorr_m dimension of input. Must have the same shape as the last dimensions of input.

output_schema : list of str or int

A schema describing the ocorr_1, ..., ocorr_n dimension of the return value.

Returns:

result : numpy.ndarray

Result of shape (dim_1, ..., dim_n, ocorr_1, ..., ocorr_m) The type may be floating point or promoted to complex depending on the combinations in output.

Notes

Only stokes parameters, linear and circular correlations are currently handled, but the full list of id’s and strings as defined in the CASA documentation is:

{{ Undefined: 0, I: 1, Q: 2, U: 3, V: 4, RR: 5, RL: 6, LR: 7, LL: 8,
    XX: 9, XY: 10, YX: 11, YY: 12, RX: 13, RY: 14, LX: 15, LY: 16,
    XR: 17, XL: 18, YR: 19, YL: 20, PP: 21, PQ: 22, QP: 23, QQ:
    24, RCircular: 25, LCircular: 26, Linear: 27, Ptotal: 28,
    Plinear: 29, PFtotal: 30, PFlinear: 31, Pangle: 32 }}

Cuda¶

convert(inputs, input_schema, output_schema) This function converts forward and backward from stokes I,Q,U,V to both linear XX,XY,YX,YY and circular RR, RL, LR, LL correlations.

africanus.model.coherency.cuda.convert(inputs, input_schema, output_schema)[source]¶

This function converts forward and backward from stokes I,Q,U,V to both linear XX,XY,YX,YY and circular RR, RL, LR, LL correlations.

For example, we can convert from stokes parameters to linear correlations:

stokes.shape == (10, 4, 4)
corrs = convert(stokes, ["I", "Q", "U", "V"],
                [['XX', 'XY'], ['YX', 'YY'])

assert corrs.shape == (10, 4, 2, 2)

Or circular correlations to stokes:

vis.shape == (10, 4, 2, 2)

stokes = convert(vis, [['RR', 'RL'], ['LR', 'LL']],
                        ['I', 'Q', 'U', 'V'])

assert stokes.shape == (10, 4, 4)

input can output can be arbitrarily nested or ordered lists, but the appropriate inputs must be present to produce the requested outputs.

The elements of input and output may be strings or integers representing stokes parameters or correlations. See the Notes for a full list.

Parameters:

input : cupy.ndarray

Complex or floating point input data of shape (dim_1, ..., dim_n, icorr_1, ..., icorr_m)

input_schema : list of str or int

A schema describing the icorr_1, ..., icorr_m dimension of input. Must have the same shape as the last dimensions of input.

output_schema : list of str or int

A schema describing the ocorr_1, ..., ocorr_n dimension of the return value.

Returns:

result : cupy.ndarray

Result of shape (dim_1, ..., dim_n, ocorr_1, ..., ocorr_m) The type may be floating point or promoted to complex depending on the combinations in output.

Notes

Only stokes parameters, linear and circular correlations are currently handled, but the full list of id’s and strings as defined in the CASA documentation is:

{{ Undefined: 0, I: 1, Q: 2, U: 3, V: 4, RR: 5, RL: 6, LR: 7, LL: 8,
    XX: 9, XY: 10, YX: 11, YY: 12, RX: 13, RY: 14, LX: 15, LY: 16,
    XR: 17, XL: 18, YR: 19, YL: 20, PP: 21, PQ: 22, QP: 23, QQ:
    24, RCircular: 25, LCircular: 26, Linear: 27, Ptotal: 28,
    Plinear: 29, PFtotal: 30, PFlinear: 31, Pangle: 32 }}

Dask¶

convert(input, input_schema, output_schema) This function converts forward and backward from stokes I,Q,U,V to both linear XX,XY,YX,YY and circular RR, RL, LR, LL correlations.

africanus.model.coherency.dask.convert(input, input_schema, output_schema)[source]¶

This function converts forward and backward from stokes I,Q,U,V to both linear XX,XY,YX,YY and circular RR, RL, LR, LL correlations.

For example, we can convert from stokes parameters to linear correlations:

stokes.shape == (10, 4, 4)
corrs = convert(stokes, ["I", "Q", "U", "V"],
                [['XX', 'XY'], ['YX', 'YY'])

assert corrs.shape == (10, 4, 2, 2)

Or circular correlations to stokes:

vis.shape == (10, 4, 2, 2)

stokes = convert(vis, [['RR', 'RL'], ['LR', 'LL']],
                        ['I', 'Q', 'U', 'V'])

assert stokes.shape == (10, 4, 4)

input can output can be arbitrarily nested or ordered lists, but the appropriate inputs must be present to produce the requested outputs.

The elements of input and output may be strings or integers representing stokes parameters or correlations. See the Notes for a full list.

Parameters:

input : dask.array.Array

Complex or floating point input data of shape (dim_1, ..., dim_n, icorr_1, ..., icorr_m)

input_schema : list of str or int

A schema describing the icorr_1, ..., icorr_m dimension of input. Must have the same shape as the last dimensions of input.

output_schema : list of str or int

A schema describing the ocorr_1, ..., ocorr_n dimension of the return value.

Returns:

result : dask.array.Array

Result of shape (dim_1, ..., dim_n, ocorr_1, ..., ocorr_m) The type may be floating point or promoted to complex depending on the combinations in output.

Notes

Only stokes parameters, linear and circular correlations are currently handled, but the full list of id’s and strings as defined in the CASA documentation is:

{{ Undefined: 0, I: 1, Q: 2, U: 3, V: 4, RR: 5, RL: 6, LR: 7, LL: 8,
    XX: 9, XY: 10, YX: 11, YY: 12, RX: 13, RY: 14, LX: 15, LY: 16,
    XR: 17, XL: 18, YR: 19, YL: 20, PP: 21, PQ: 22, QP: 23, QQ:
    24, RCircular: 25, LCircular: 26, Linear: 27, Ptotal: 28,
    Plinear: 29, PFtotal: 30, PFlinear: 31, Pangle: 32 }}

Spectral Model¶

Functionality for computing a Spectral Model.

Numpy¶

spectral_model(stokes, spi, ref_freq, frequency) Compute a spectral model, per polarisation.

africanus.model.spectral.spectral_model(stokes, spi, ref_freq, frequency, base=0)[source]¶

Compute a spectral model, per polarisation.

\begin{eqnarray} I(\lambda) & = & \sum_{i=0} \alpha_{i} (\lambda / \lambda_0 - 1)^i \, \textrm{where} \, \alpha_0 = I(\lambda_0) \\ \ln( I(\lambda) ) & = & \sum_{i=0} \alpha_{i} \ln (\lambda / \lambda_0)^i \, \textrm{where} \, \alpha_0 = \ln I_0 \\ \log_{10}( I(\lambda) ) & = & \sum_{i=0} \alpha_{i} \log_{10} (\lambda / \lambda_0)^i \, \textrm{where} \, \alpha_0 = \log_{10} I_0 \\ \end{eqnarray}

Parameters:

stokes : numpy.ndarray

Stokes parameters of shape (source,) or (source, pol). If a pol dimension is present, then it must also be present on spi.

spi : numpy.ndarray

Spectral index of shape (source, spi-comps) or (source, spi-comps, pol).

ref_freq : numpy.ndarray

Reference frequencies of shape (source,)

frequencies : numpy.ndarray

Frequencies of shape (chan,)

base : {“std”, “log”, “log10”} or {0, 1, 2} or list.

string or corresponding enumeration specifying the polynomial base. Defaults to 0.

If a list is provided, a polynomial base can be specified for each stokes parameter or polarisation in the pol dimension.

string specification of the base is only supported in python 3. while the corresponding integer enumerations are supported on all python versions.

Returns:

spectral_model : numpy.ndarray

Spectral Model of shape (source, chan) or (source, chan, pol).

Dask¶

spectral_model(stokes, spi, ref_freq, …[, …]) Compute a spectral model, per polarisation.

africanus.model.spectral.dask.spectral_model(stokes, spi, ref_freq, frequencies, base=0)[source]¶

Compute a spectral model, per polarisation.

\begin{eqnarray} I(\lambda) & = & \sum_{i=0} \alpha_{i} (\lambda / \lambda_0 - 1)^i \, \textrm{where} \, \alpha_0 = I(\lambda_0) \\ \ln( I(\lambda) ) & = & \sum_{i=0} \alpha_{i} \ln (\lambda / \lambda_0)^i \, \textrm{where} \, \alpha_0 = \ln I_0 \\ \log_{10}( I(\lambda) ) & = & \sum_{i=0} \alpha_{i} \log_{10} (\lambda / \lambda_0)^i \, \textrm{where} \, \alpha_0 = \log_{10} I_0 \\ \end{eqnarray}

Parameters:

stokes : dask.array.Array

Stokes parameters of shape (source,) or (source, pol). If a pol dimension is present, then it must also be present on spi.

spi : dask.array.Array

Spectral index of shape (source, spi-comps) or (source, spi-comps, pol).

ref_freq : dask.array.Array

Reference frequencies of shape (source,)

frequencies : dask.array.Array

Frequencies of shape (chan,)

base : {“std”, “log”, “log10”} or {0, 1, 2} or list.

string or corresponding enumeration specifying the polynomial base. Defaults to 0.

If a list is provided, a polynomial base can be specified for each stokes parameter or polarisation in the pol dimension.

string specification of the base is only supported in python 3. while the corresponding integer enumerations are supported on all python versions.

Returns:

spectral_model : dask.array.Array

Spectral Model of shape (source, chan) or (source, chan, pol).

Spectral Index¶

Functionality related to the spectral index.

For example, we may want to compute the spectral indices of components in a sky model defined by

\[I(\nu) = I(\nu_0) \left(\frac{\nu}{\nu_0}\right)^\alpha\]

where $\nu$ are frequencies ay which we want to construct the intensity of a Stokes I image and the $\nu_0$ is the corresponding reference frequency. The spectral index $\alpha$ determines how quickly the intensity grows or decays as a function of frequency. Given a list of model image components (preferably with the residuals added back in) we can recover the corresponding spectral indices and reference intensities using the fit_spi_components() function. This will also return a lower bound on the associated uncertainties on these components.

Numpy¶

fit_spi_components(data, weights, freqs, freq0) Computes the spectral indices and the intensity at the reference frequency of a spectral index model:

africanus.model.spi.fit_spi_components(data, weights, freqs, freq0, alphai=None, I0i=None, tol=0.0001, maxiter=100)[source]¶

Computes the spectral indices and the intensity at the reference frequency of a spectral index model:

\[I(\nu) = I(\nu_0) \left( \frac{\nu}{\nu_0} \right) ^ \alpha\]

Parameters:

data : numpy.ndarray

array of shape (comps, chan) The noisy data as a function of frequency.

weights : numpy.ndarray

array of shape (chan,) Inverse of variance on each frequency axis.

freqs : numpy.ndarray

frequencies of shape (chan,)

freq0 : float

Reference frequency

alphai : numpy.ndarray, optional

array of shape (comps,) Initial guess for the alphas. Defaults to -0.7.

I0i : numpy.ndarray, optional

array of shape (comps,) Initial guess for the intensities at the reference frequency. Defaults to 1.0.

tol : float, optional

Solver absolute tolerance (optional). Defaults to 1e-6.

maxiter : int, optional

Solver maximum iterations (optional). Defaults to 100.

dtype : np.dtype, optional

Datatype of result. Should be either np.float32 or np.float64. Defaults to np.float64.

Returns:

out : numpy.ndarray

array of shape (4, comps) The fitted components arranged as [alphas, alphavars, I0s, I0vars]

Dask¶

fit_spi_components(data, weights, freqs, freq0) Computes the spectral indices and the intensity at the reference frequency of a spectral index model:

africanus.model.spi.dask.fit_spi_components(data, weights, freqs, freq0, alphai=None, I0i=None, tol=1e-05, maxiter=100)[source]¶

Computes the spectral indices and the intensity at the reference frequency of a spectral index model:

\[I(\nu) = I(\nu_0) \left( \frac{\nu}{\nu_0} \right) ^ \alpha\]

Parameters:

data : dask.array.Array

array of shape (comps, chan) The noisy data as a function of frequency.

weights : dask.array.Array

array of shape (chan,) Inverse of variance on each frequency axis.

freqs : dask.array.Array

frequencies of shape (chan,)

freq0 : float

Reference frequency

alphai : dask.array.Array, optional

array of shape (comps,) Initial guess for the alphas. Defaults to -0.7.

I0i : dask.array.Array, optional

array of shape (comps,) Initial guess for the intensities at the reference frequency. Defaults to 1.0.

tol : float, optional

Solver absolute tolerance (optional). Defaults to 1e-6.

maxiter : int, optional

Solver maximum iterations (optional). Defaults to 100.

dtype : np.dtype, optional

Datatype of result. Should be either np.float32 or np.float64. Defaults to np.float64.

Returns:

out : dask.array.Array

array of shape (4, comps) The fitted components arranged as [alphas, alphavars, I0s, I0vars]

Source Morphology¶

Shape functions for different Source Morphologies

Numpy¶

gaussian(uvw, frequency, shape_params) Computes the Gaussian Shape Function.

africanus.model.shape.gaussian(uvw, frequency, shape_params)[source]¶

Computes the Gaussian Shape Function.

\[\begin{split}& \lambda^\prime = 2 \lambda \pi \\ & r = \frac{e_{min}}{e_{maj}} \\ & u_{1} = (u \, e_{maj} \, cos(\alpha) - v \, e_{maj} \, sin(\alpha)) r \lambda^\prime \\ & v_{1} = (u \, e_{maj} \, sin(\alpha) - v \, e_{maj} \, cos(\alpha)) \lambda^\prime \\ & \textrm{shape} = e^{(-u_{1}^2 - v_{1}^2)}\end{split}\]

where:

$u$ and $v$ are the UV coordinates and $\lambda$ the frequency.
$e_{maj}$ and $e_{min}$ are the major and minor axes and $\alpha$ the position angle.

Parameters:

uvw : numpy.ndarray

UVW coordinates of shape (row, 3)

frequency : numpy.ndarray

frequencies of shape (chan,)

shape_param : numpy.ndarray

Gaussian Shape Parameters of shape (source, 3) where the second dimension contains the (emajor, eminor, angle) parameters describing the shape of the Gaussian

Returns:

gauss_shape : numpy.ndarray

Shape parameters of shape (source, row, chan)

Dask¶

gaussian(uvw, frequency, shape_params) Computes the Gaussian Shape Function.

africanus.model.shape.dask.gaussian(uvw, frequency, shape_params)[source]¶

Computes the Gaussian Shape Function.

\[\begin{split}& \lambda^\prime = 2 \lambda \pi \\ & r = \frac{e_{min}}{e_{maj}} \\ & u_{1} = (u \, e_{maj} \, cos(\alpha) - v \, e_{maj} \, sin(\alpha)) r \lambda^\prime \\ & v_{1} = (u \, e_{maj} \, sin(\alpha) - v \, e_{maj} \, cos(\alpha)) \lambda^\prime \\ & \textrm{shape} = e^{(-u_{1}^2 - v_{1}^2)}\end{split}\]

where:

$u$ and $v$ are the UV coordinates and $\lambda$ the frequency.
$e_{maj}$ and $e_{min}$ are the major and minor axes and $\alpha$ the position angle.

Parameters:

uvw : dask.array.Array

UVW coordinates of shape (row, 3)

frequency : dask.array.Array

frequencies of shape (chan,)

shape_param : dask.array.Array

Gaussian Shape Parameters of shape (source, 3) where the second dimension contains the (emajor, eminor, angle) parameters describing the shape of the Gaussian

Returns:

gauss_shape : dask.array.Array

Shape parameters of shape (source, row, chan)

WSClean Spectral Model¶

Utilities for creating a spectral model from a wsclean component file.

Numpy¶

`load`(filename)	Loads wsclean component model.
`spectra`(I, coeffs, log_poly, ref_freq, frequency)	Produces a spectral model from a polynomial expansion of a wsclean file model.

africanus.model.wsclean.load(filename)[source]¶

Loads wsclean component model.

sources = load("components.txt")
sources = dict(sources)  # Convert to dictionary

I = sources["I"]
ref_freq = sources["ReferenceFrequency"]

See the WSClean Component List for further details.

Parameters:

filename : str or iterable

Filename of wsclean model file or iterable producing the lines of the file.

Returns:

list of (name, list of values) tuples

list of column (name, value) tuples

Dask¶

spectra(stokes, spi, log_si, ref_freq, frequency) Produces a spectral model from a polynomial expansion of a wsclean file model.

africanus.model.wsclean.dask.spectra(stokes, spi, log_si, ref_freq, frequency)[source]¶

Produces a spectral model from a polynomial expansion of a wsclean file model. Depending on how log_poly is set ordinary or logarithmic polynomials are used to produce the expansion:

\[\begin{split}& flux(\lambda) = I_{0} + \sum\limits_{c=0} \textrm{coeffs}(c) ({\lambda/\lambda_{ref}} - 1)^{c+1} \\ & flux(\lambda) = \exp \left( \log I_{0} + \sum\limits_{c=0} \textrm{coeffs}(c) \log({\lambda/\lambda_{ref}})^{c+1} \right) \\\end{split}\]

See the WSClean Component List for further details.

Parameters:

I : dask.array.Array

flux density in Janskys at the reference frequency of shape (source,)

coeffs : dask.array.Array

Polynomial coefficients for each source of shape (source, comp)

log_poly : dask.array.Array or bool

boolean array of shape (source, ) indicating whether logarithmic (True) or ordinary (False) polynomials should be used.

ref_freq : dask.array.Array

Source reference frequencies of shape (source,)

frequency : dask.array.Array

frequencies of shape (chan,)

Returns:

spectral_model : dask.array.Array

Spectral Model of shape (source, chan)

Averaging¶

Routines for averaging visibility data.

Time and Channel Averaging¶

The routines in this section average row-based samples by:

Averaging samples of consecutive time values into bins defined by an period of time_bin_secs seconds.
Averaging channel data into equally sized bins of chan_bin_size.

In order to achieve this, a baseline x time ordering is established over the input data where baseline corresponds to the unique (ANTENNA1, ANTENNA2) pairs and time corresponds to the unique, monotonically increasing TIME values associated with the rows of a Measurement Set.

Baseline	T0	T1	T2	T3	T4
(0, 0)	0.1	0.2	0.3	0.4	0.5
(0, 1)	0.1	0.2	0.3	0.4	0.5
(0, 2)	0.1	0.2	X	0.4	0.5
(1, 1)	0.1	0.2	0.3	0.4	0.5
(1, 2)	0.1	0.2	0.3	0.4	0.5
(2, 2)	0.1	0.2	0.3	0.4	0.5

It is possible for times or baselines to be missing. In the above example, T2 is missing for baseline (0, 2).

Warning

The above requires unique lexicographical combinations of (TIME, ANTENNA1, ANTENNA2). This can usually be achieved by suitably partitioning input data on indexing rows, DATA_DESC_ID and SCAN_NUMBER in particular.

For each baseline, adjacent time’s are assigned to a bin if $h_c - h_e/2 - (l_c - l_e/2) <$ time_bin_secs, where $h_c$ and $l_c$ are the upper and lower time and $h_e$ and $l_e$ are the upper and lower intervals, taken from the INTERVAL column. Note that no distinction is made between flagged and unflagged data when establishing the endpoints in the bin.

The reason for this is that the Measurement Set v2.0 Specification specifies that TIME and INTERVAL columns are defined as containing the nominal time and period at which the visibility was sampled. This means that their values includie valid, flagged and missing data. Thus, averaging a regular high-resolution baseline x htime grid should produce a regular low-resolution baseline x ltime grid (htime > ltime) in the presence of bad data

By contrast, other columns such as TIME_CENTROID and EXPOSURE contain the effective time and period as they exclude missing and bad data. Their increased accuracy, and therefore variability means that they are unsuitable for establishing a grid over the data.

To summarise, the averaged times in each bin establish a map:

from possibly unordered input rows.
to a reduced set of output rows ordered by averaged (TIME, ANTENNA1, ANTENNA2).

Flagged Data Handling¶

Both FLAG_ROW and FLAG columns may be supplied to the averager, but they should be consistent with each other. The averager will throw an exception if this is not the case, rather than making an assumption as to which is correct.

When provided with flags, the averager will output averages for bins that are completely flagged.

Part of the reason for this is that the specifies that the TIME and INTERVAL columns represent the nominal time and interval values. This means that they should represent valid as well as flagged or missing data in their computation.

By contrast, most other columns such as TIME_CENTROID and EXPOSURE, contain the effective values and should only include valid, unflagged data.

To support this:

TIME and INTERVAL are averaged using both flagged and unflagged samples.
Other columns, such as TIME_CENTROID are handled as follows:
1. If the bin contains some unflagged data, only this data is used to calculate average.
2. If the bin is completely flagged, the average of all samples (which are all flagged) will be used.
In both cases, a completely flagged bin will have it’s flag set.
To support the two cases, twice the memory of the output array is required to track both averages, but only one array of merged values is returned.

Guarantees¶

Averaged output data will be lexicographically ordered by (TIME, ANTENNA1, ANTENNA2)
TIME and INTERVAL columns always contain the nominal average and sum and therefore contain both and missing or unflagged data.
Other columns will contain the effective average and will contain only valid data except when all data in the bin is flagged.
Completely flagged bins will be set as flagged in both the nominal and effective case.
Certain columns are averaged, while others are summed, or simply assigned to the last value in the bin in the case of antenna indices.
Visibility data is averaged by multiplying and dividing by WEIGHT_SPECTRUM or WEIGHT or natural weighting, in order of priority.

\[\frac{\sum v_i w_i}{\sum w_i}\]

SIGMA_SPECTRUM is averaged by multiplying and dividing by WEIGHT_SPECTRUM or WEIGHT or natural weighting, in order of priority and availability.

SIGMA is only averaged with WEIGHT or natural weighting.

\[\sqrt{\frac{\sum w_i^2 \sigma_i^2}{(\sum w_i)^2}}\]

The following table summarizes the handling of each column in the main Measurement Set table:

Column	Unflagged/Flagged sample handling	Aggregation Method	Required
TIME	Nominal	Mean	Yes
INTERVAL	Nominal	Sum	Yes
ANTENNA1	Nominal	Assigned to Last Input	Yes
ANTENNA2	Nominal	Assigned to Last Input	Yes
TIME_CENTROID	Effective	Mean	No
EXPOSURE	Effective	Sum	No
FLAG_ROW	Effective	Set if All Inputs Flagged	No
UVW	Effective	Mean	No
WEIGHT	Effective	Sum	No
SIGMA	Effective	Weighted Mean	No
DATA (vis)	Effective	Weighted Mean	No
FLAG	Effective	Set if All Inputs Flagged	No
WEIGHT_SPECTRUM	Effective	Sum	No
SIGMA_SPECTRUM	Effective	Weighted Mean	No

The following SPECTRAL_WINDOW sub-table columns are averaged as follows:

Column	Aggregation Method
CHAN_FREQ	Mean
CHAN_WIDTH	Sum
EFFECTIVE_BW	Sum
RESOLUTION	Sum

Dask Implementation¶

The dask implementation chunks data up by row and channel and averages each chunk independently of values in other chunks. This should be kept in mind if one wishes to maintain a particular ordering in the output dask arrays.

Typically, Measurement Set data is monotonically ordered in time. To maintain this guarantee in output dask arrays, the chunks will need to be separated by distinct time values. Practically speaking this means that the first and second chunk should not both contain value time 0.1, for example.

Numpy¶

time_and_channel(time, interval, antenna1, …) Averages in time and channel.

africanus.averaging.time_and_channel(time, interval, antenna1, antenna2, time_centroid=None, exposure=None, flag_row=None, uvw=None, weight=None, sigma=None, chan_freq=None, chan_width=None, effective_bw=None, resolution=None, vis=None, flag=None, weight_spectrum=None, sigma_spectrum=None, time_bin_secs=1.0, chan_bin_size=1)[source]¶

Averages in time and channel.

Parameters:

time : numpy.ndarray

Time values of shape (row,).

interval : numpy.ndarray

Interval values of shape (row,).

antenna1 : numpy.ndarray

First antenna indices of shape (row,)

antenna2 : numpy.ndarray

Second antenna indices of shape (row,)

time_centroid : numpy.ndarray, optional

Time centroid values of shape (row,)

exposure : numpy.ndarray, optional

Exposure values of shape (row,)

flag_row : numpy.ndarray, optional

Flagged rows of shape (row,).

uvw : numpy.ndarray, optional

UVW coordinates of shape (row, 3).

weight : numpy.ndarray, optional

Weight values of shape (row, corr).

sigma : numpy.ndarray, optional

Sigma values of shape (row, corr).

chan_freq : numpy.ndarray, optional

Channel frequencies of shape (chan,).

chan_width : numpy.ndarray, optional

Channel widths of shape (chan,).

effective_bw : numpy.ndarray, optional

Effective channel bandwidth of shape (chan,).

resolution : numpy.ndarray, optional

Effective channel resolution of shape (chan,).

vis : numpy.ndarray, optional

Visibility data of shape (row, chan, corr).

flag : numpy.ndarray, optional

Flag data of shape (row, chan, corr).

weight_spectrum : numpy.ndarray, optional

Weight spectrum of shape (row, chan, corr).

sigma_spectrum : numpy.ndarray, optional

Sigma spectrum of shape (row, chan, corr).

time_bin_secs : float, optional

Maximum summed interval in seconds to include within a bin. Defaults to 1.0.

chan_bin_size : int, optional

Number of bins to average together. Defaults to 1.

Returns:

namedtuple

A namedtuple whose entries correspond to the input arrays. Output arrays will be None if the inputs were None.

Notes

The implementation currently requires unique lexicographical combinations of (TIME, ANTENNA1, ANTENNA2). This can usually be achieved by suitably partitioning input data on indexing rows, DATA_DESC_ID and SCAN_NUMBER in particular.

Dask¶

time_and_channel(time, interval, antenna1, …) Averages in time and channel.

africanus.averaging.dask.time_and_channel(time, interval, antenna1, antenna2, time_centroid=None, exposure=None, flag_row=None, uvw=None, weight=None, sigma=None, chan_freq=None, chan_width=None, effective_bw=None, resolution=None, vis=None, flag=None, weight_spectrum=None, sigma_spectrum=None, time_bin_secs=1.0, chan_bin_size=1)[source]¶

Averages in time and channel.

Parameters:

time : dask.array.Array

Time values of shape (row,).

interval : dask.array.Array

Interval values of shape (row,).

antenna1 : dask.array.Array

First antenna indices of shape (row,)

antenna2 : dask.array.Array

Second antenna indices of shape (row,)

time_centroid : dask.array.Array, optional

Time centroid values of shape (row,)

exposure : dask.array.Array, optional

Exposure values of shape (row,)

flag_row : dask.array.Array, optional

Flagged rows of shape (row,).

uvw : dask.array.Array, optional

UVW coordinates of shape (row, 3).

weight : dask.array.Array, optional

Weight values of shape (row, corr).

sigma : dask.array.Array, optional

Sigma values of shape (row, corr).

chan_freq : dask.array.Array, optional

Channel frequencies of shape (chan,).

chan_width : dask.array.Array, optional

Channel widths of shape (chan,).

effective_bw : dask.array.Array, optional

Effective channel bandwidth of shape (chan,).

resolution : dask.array.Array, optional

Effective channel resolution of shape (chan,).

vis : dask.array.Array, optional

Visibility data of shape (row, chan, corr).

flag : dask.array.Array, optional

Flag data of shape (row, chan, corr).

weight_spectrum : dask.array.Array, optional

Weight spectrum of shape (row, chan, corr).

sigma_spectrum : dask.array.Array, optional

Sigma spectrum of shape (row, chan, corr).

time_bin_secs : float, optional

Maximum summed interval in seconds to include within a bin. Defaults to 1.0.

chan_bin_size : int, optional

Number of bins to average together. Defaults to 1.

Returns:

namedtuple

A namedtuple whose entries correspond to the input arrays. Output arrays will be None if the inputs were None.

Notes

The implementation currently requires unique lexicographical combinations of (TIME, ANTENNA1, ANTENNA2). This can usually be achieved by suitably partitioning input data on indexing rows, DATA_DESC_ID and SCAN_NUMBER in particular.

Utilities¶

Command Line¶

parse_python_assigns(assign_str) Parses a string, containing assign statements into a dictionary.

africanus.util.cmdline.parse_python_assigns(assign_str)[source]¶

Parses a string, containing assign statements into a dictionary.

data = parse_python_assigns("beta=5.6; l=[2,3], s='hello, world'")

assert data == {
    'beta': 5.6,
    'l': [2, 3],
    's': 'hello, world'
}

Parameters:

assign_str: str

Assignment string. Should only contain assignment statements assigning python literals or builtin function calls, to variable names. Multiple assignment statements should be separated by semi-colons.

Returns:

dict

Dictionary { name: value } containing assignment results.

Requirements Handling¶

requires_optional(*requirements) Decorator returning either the original function, or a dummy function raising a MissingPackageException when called, depending on whether the supplied requirements are present.

africanus.util.requirements.requires_optional(*requirements)[source]¶

Decorator returning either the original function, or a dummy function raising a MissingPackageException when called, depending on whether the supplied requirements are present.

If packages are missing and called within a test, the dummy function will call pytest.skip().

Used in the following way:

try:
    from scipy import interpolate
except ImportError as e:
    # https://stackoverflow.com/a/29268974/1611416, pep 3110 and 344
    scipy_import_error = e
else:
    scipy_import_error = None

@requires_optional('scipy', scipy_import_error)
def function(*args, **kwargs):
    return interpolate(...)

Parameters:

requirements : iterable of string, None or ImportError

Sequence of package names required by the decorated function. ImportError exceptions (or None, indicating their absence) may also be supplied and will be immediately re-raised within the decorator. This is useful for tracking down problems in user import logic.

Returns:

callable

Either the original function if all requirements are available or a dummy function that throws a MissingPackageException or skips a pytest.

Shapes¶

`aggregate_chunks`(chunks, max_chunks)	Aggregate dask `chunks` together into chunks no larger than `max_chunks`.
`corr_shape`(ncorr, corr_shape)	Returns the shape of the correlations, given `ncorr` and the type of correlation shape requested

africanus.util.shapes.aggregate_chunks(chunks, max_chunks)[source]¶

Aggregate dask chunks together into chunks no larger than max_chunks.

chunks, max_c = ((3,4,6,3,6,7),(1,1,1,1,1,1)), (10,3)
expected = ((7,9,6,7), (2,2,1,1))
assert aggregate_chunks(chunks, max_c) == expected

Parameters:

chunks : sequence of tuples or tuple

max_chunks : sequence of ints or int

Returns:

sequence of tuples or tuple

africanus.util.shapes.corr_shape(ncorr, corr_shape)[source]¶

Returns the shape of the correlations, given ncorr and the type of correlation shape requested

Parameters:

ncorr : integer

Number of correlations

corr_shape : {‘flat’, ‘matrix’}

Shape of output correlations

Returns:

tuple

Shape tuple describing the correlation dimensions

If flat returns (ncorr,)

If matrix returns

(1,) if ncorr == 1

(2,) if ncorr == 2

(2,2) if ncorr == 4

Beams¶

`beam_filenames`(filename_schema, corr_types)	Returns a dictionary of beam filename pairs, keyed on correlation,from the cartesian product of correlations and real, imaginary pairs
`beam_grids`(header)	Extracts the FITS indices and grids for the beam dimensions in the supplied FITS `header`.

africanus.util.beams.beam_filenames(filename_schema, corr_types)[source]¶

Returns a dictionary of beam filename pairs, keyed on correlation,from the cartesian product of correlations and real, imaginary pairs

Given beam_$(corr)_$(reim).fits returns:

{
  'xx' : ['beam_xx_re.fits', 'beam_xx_im.fits'],
  'xy' : ['beam_xy_re.fits', 'beam_xy_im.fits'],
  ...
  'yy' : ['beam_yy_re.fits', 'beam_yy_im.fits'],
}

Given beam_$(CORR)_$(REIM).fits returns:

{
  'xx' : ['beam_XX_RE.fits', 'beam_XX_IM.fits'],
  'xy' : ['beam_XY_RE.fits', 'beam_XY_IM.fits'],
  ...
  'yy' : ['beam_YY_RE.fits', 'beam_YY_IM.fits']),
}

Parameters:

filename_schema : str

String containing the filename schema.

corr_types : list of integers

list of integers defining the correlation type.

Returns:

dict

Dictionary of schema {correlation : (refile, imfile)} mapping correlations to real and imaginary filename pairs

africanus.util.beams.beam_grids(header)[source]¶

Extracts the FITS indices and grids for the beam dimensions in the supplied FITS header. Specifically the axes specified by

L or X CTYPE
M or Y CTYPE
FREQ CTYPE

If the first two axes have a negative sign, such as -L, the grid will be inverted.

Any grids corresponding to axes with a CUNIT type of DEG will be converted to radians.

Parameters:

header : Header or dict

FITS header object.

Returns:

tuple

Returns ((l_axis, l_grid), (m_axis, m_grid), (freq_axis, freq_grid)) where the axis is the FORTRAN indexed FITS axis (1-indexed) and grid contains the values at each pixel along the axis.

Code¶

`format_code`(code)	Formats some code with line numbers
`memoize_on_key`(key_fn)	Memoize based on a key function supplied by the user.

africanus.util.code.format_code(code)[source]¶

Formats some code with line numbers

Parameters:

code : str

Code

Returns:

str

Code prefixed with line numbers

class africanus.util.code.memoize_on_key(key_fn)[source]¶

Memoize based on a key function supplied by the user. The key function should return a custom key for memoizing the decorated function, based on the arguments passed to it.

In the following example, the arguments required to generate the _generate_phase_delay_kernel function are the types of the lm, uvw and frequency arrays, as well as the number of correlations, ncorr.

The supplied key_fn produces a unique key based on these types and the number of correlations, which is used to cache the generated function.

def key_fn(lm, uvw, frequency, ncorrs=4):
    '''
    Produce a unique key for the arguments of
     _generate_phase_delay_kernel
    '''
    return (lm.dtype, uvw.dtype, frequency.dtype, ncorrs)

_code_template = jinja2.Template('''
#define ncorrs {{ncorrs}}

__global__ void phase_delay(
    const {{lm_type}} * lm,
    const {{uvw_type}} * uvw,
    const {{freq_type}} * frequency,
    {{out_type}} * out)
{
    ...
}
''')

_type_map = {
    np.float32: 'float',
    np.float64: 'double'
}

@memoize_on_key(key_fn)
def _generate_phase_delay_kernel(lm, uvw, frequency, ncorrs=4):
    ''' Generate the phase delay kernel '''
    out_dtype = np.result_type(lm.dtype, uvw.dtype, frequency.dtype)
    code = _code_template.render(lm_type=_type_map[lm.dtype],
                                 uvw_type=_type_map[uvw.dtype],
                                 freq_type=_type_map[frequency.dtype],
                                 ncorrs=ncorrs)
    return cp.RawKernel(code, "phase_delay")

Methods

__call__(fn) Call self as a function.

dask¶

EstimatingProgressBar([minimum, width, dt, out]) Progress Bar that displays elapsed time as well as an estimate of total time taken.

class africanus.util.dask_util.EstimatingProgressBar(minimum=0, width=42, dt=1.0, out=sys.stdout)[source]¶

Progress Bar that displays elapsed time as well as an estimate of total time taken.

When starting a dask computation, the bar examines the graph and determines the number of chunks contained by a dask collection.

During computation the number of completed chunks and their the total time taken to complete them are tracked. The average derived from these numbers are used to estimate total compute time, relative to the current elapsed time.

The bar is not particularly accurate and will underestimate near the beginning of computation and seems to slightly overestimate during the buk of computation. However, it may be more accurate than the default dask task bar which tracks number of tasks completed by total tasks.

Parameters:

minimum : int, optional

Minimum time threshold in seconds before displaying a progress bar. Default is 0 (always display)

width : int, optional

Width of the bar, default is 42 characters.

dt : float, optional

Update resolution in seconds, default is 1.0 seconds.

CUDA¶

grids(dims, blocks) Determine the grid size, given space dimensions sizes and blocks

africanus.util.cuda.grids(dims, blocks)[source]¶

Determine the grid size, given space dimensions sizes and blocks

Parameters:

dims : tuple of ints

(x, y, z) tuple

Returns:

tuple

(x, y, z) grid size tuple

Calibration¶

This module provides basic radio interferometry calibration utilities. Calibration is the process of estimating the $2\times 2$ Jones matrices which describe transformations of the signal as it propagates from source to observer. Currently, all utilities assume a discretised form of the radio interferometer measurement equation (RIME) as described in Radio Interferometer Measurement Equation.

Calibration is usually divided into three phases viz.

First generation calibration (1GC): using an external calibrator to infer the gains during the target observation. Sometimes also refered to as calibrator transfer
Second generation calibration (2GC): using a partially incomplete sky model to perform direction independent calibration. Also known as direction independent self-calibration.
Third generation calibration (3GC): using a partially incomplete sky model to perform direction dependent calibration. Also known as direction dependent self-calibration.

On top of these three phases, there are usually three possible calibration scenarios. The first is when both the Jones terms and the visibilities are assumed to be diagonal. In this case the two correlations can be calibrated separately and it is refered to as diag-diag calibration. The second case is when the Jones matrices are assumed to be diagonal but the visibility data are full $2\times 2$ matrices. This is refered to as diag calibration. The final scenario is when both the full $2\times 2$ Jones matrices and the full $2\times 2$ visibilities are used for calibration. This is simply refered to as calibration. The specific scenario is determined from the shapes of the input gains and the input data.

This module also provides a number of utilities which are useful for calibration.

Utils¶

Numpy¶

`corrupt_vis`(time_bin_indices, …)	Corrupts model visibilities with arbitrary Jones terms.
`residual_vis`(time_bin_indices, …)	Computes residual visibilities given model visibilities and gains solutions.
`correct_vis`(time_bin_indices, …)	Apply inverse of direction independent gains to visibilities to generate corrected visibilities.
`compute_and_corrupt_vis`(time_bin_indices, …)	Corrupts time variable component model with arbitrary Jones terms.

africanus.calibration.utils.corrupt_vis(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, model)[source]¶

Corrupts model visibilities with arbitrary Jones terms.

Parameters:

time_bin_indices : numpy.ndarray

The start indices of the time bins of shape (utime)

time_bin_counts : numpy.ndarray

The counts of unique time in each time bin of shape (utime)

antenna1 : numpy.ndarray

First antenna indices of shape (row,).

antenna2 : numpy.ndarray

Second antenna indices of shape (row,)

jones : numpy.ndarray

Gains of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

model : numpy.ndarray

Model data values of shape (row, chan, dir, corr) or (row, chan, dir, corr, corr).

Returns:

vis : numpy.ndarray

visibilities of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

africanus.calibration.utils.residual_vis(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, vis, flag, model)[source]¶

Computes residual visibilities given model visibilities and gains solutions.

Parameters:

time_bin_indices : numpy.ndarray

The start indices of the time bins of shape (utime)

time_bin_counts : numpy.ndarray

The counts of unique time in each time bin of shape (utime)

antenna1 : numpy.ndarray

First antenna indices of shape (row,).

antenna2 : numpy.ndarray

Second antenna indices of shape (row,)

jones : numpy.ndarray

Gain solutions of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

vis : numpy.ndarray

Data values of shape (row, chan, corr). or (row, chan, corr, corr).

flag : numpy.ndarray

Flag data of shape (row, chan, corr) or (row, chan, corr, corr)

model : numpy.ndarray

Model data values of shape (row, chan, dir, corr) or (row, chan, dir, corr, corr).

Returns:

residual : numpy.ndarray

Residual visibilities of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

africanus.calibration.utils.correct_vis(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, vis, flag)[source]¶

Apply inverse of direction independent gains to visibilities to generate corrected visibilities. For a measurement model of the form

\[V_{pq} = G_{p} X_{pq} G_{q}^H + n_{pq}\]

the corrected visibilities are defined as

\[C_{pq} = G_{p}^{-1} V_{pq} G_{q}^{-H}\]

The corrected visibilities therefore have a non-trivial noise contribution. Note it is only possible to form corrected data from direction independent gains solutions so the dir axis on the jones terms should always be one.

Parameters:

time_bin_indices : numpy.ndarray

The start indices of the time bins of shape (utime).

time_bin_counts : numpy.ndarray

The counts of unique time in each time bin of shape (utime).

antenna1 : numpy.ndarray

Antenna 1 index used to look up the antenna Jones for a particular baseline with shape (row,).

antenna2 : numpy.ndarray

Antenna 2 index used to look up the antenna Jones for a particular baseline with shape (row,).

jones : numpy.ndarray

Gain solutions of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

vis : numpy.ndarray

Data values of shape (row, chan, corr) or (row, chan, corr, corr).

flag : numpy.ndarray

Flag data of shape (row, chan, corr) or (row, chan, corr, corr).

Returns

——-

corrected_vis : numpy.ndarray

True visibilities of shape (row,chan,corr_1,corr_2)

africanus.calibration.utils.compute_and_corrupt_vis(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, model, uvw, freq, lm)[source]¶

Corrupts time variable component model with arbitrary Jones terms. Currrently only time variable point source models are supported.

Parameters:

time_bin_indices : numpy.ndarray

The start indices of the time bins of shape (utime)

time_bin_counts : numpy.ndarray

The counts of unique time in each time bin of shape (utime)

antenna1 : numpy.ndarray

First antenna indices of shape (row,).

antenna2 : numpy.ndarray

Second antenna indices of shape (row,)

jones : numpy.ndarray

Gains of shape (utime, ant, chan, dir, corr) or (utime, ant, chan, dir, corr, corr).

model : numpy.ndarray

Model image as a function of time with shape (utime, chan, dir, corr) or (utime, chan, dir, corr, corr).

uvw : numpy.ndarray

uvw coordinates of shape (row, 3)

Source lm coordinates as a function of time (utime, dir, 2)

Returns:

vis : numpy.ndarray

visibilities of shape (row, chan, corr) or (row, chan, corr, corr).

Dask¶

`corrupt_vis`(time_bin_indices, …)	Corrupts model visibilities with arbitrary Jones terms.
`residual_vis`(time_bin_indices, …)	Computes residual visibilities given model visibilities and gains solutions.
`correct_vis`(time_bin_indices, …)	Apply inverse of direction independent gains to visibilities to generate corrected visibilities.
`compute_and_corrupt_vis`(time_bin_indices, …)	Corrupts time variable component model with arbitrary Jones terms.

africanus.calibration.utils.dask.corrupt_vis(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, model)[source]¶

Corrupts model visibilities with arbitrary Jones terms.

Parameters:

time_bin_indices : dask.array.Array

The start indices of the time bins of shape (utime)

time_bin_counts : dask.array.Array

The counts of unique time in each time bin of shape (utime)

antenna1 : dask.array.Array

First antenna indices of shape (row,).

antenna2 : dask.array.Array

Second antenna indices of shape (row,)

jones : dask.array.Array

Gains of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

model : dask.array.Array

Model data values of shape (row, chan, dir, corr) or (row, chan, dir, corr, corr).

Returns:

vis : dask.array.Array

visibilities of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

africanus.calibration.utils.dask.residual_vis(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, vis, flag, model)[source]¶

Computes residual visibilities given model visibilities and gains solutions.

Parameters:

time_bin_indices : dask.array.Array

The start indices of the time bins of shape (utime)

time_bin_counts : dask.array.Array

The counts of unique time in each time bin of shape (utime)

antenna1 : dask.array.Array

First antenna indices of shape (row,).

antenna2 : dask.array.Array

Second antenna indices of shape (row,)

jones : dask.array.Array

Gain solutions of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

vis : dask.array.Array

Data values of shape (row, chan, corr). or (row, chan, corr, corr).

flag : dask.array.Array

Flag data of shape (row, chan, corr) or (row, chan, corr, corr)

model : dask.array.Array

Model data values of shape (row, chan, dir, corr) or (row, chan, dir, corr, corr).

Returns:

residual : dask.array.Array

Residual visibilities of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

africanus.calibration.utils.dask.correct_vis(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, vis, flag)[source]¶

Apply inverse of direction independent gains to visibilities to generate corrected visibilities. For a measurement model of the form

\[V_{pq} = G_{p} X_{pq} G_{q}^H + n_{pq}\]

the corrected visibilities are defined as

\[C_{pq} = G_{p}^{-1} V_{pq} G_{q}^{-H}\]

The corrected visibilities therefore have a non-trivial noise contribution. Note it is only possible to form corrected data from direction independent gains solutions so the dir axis on the jones terms should always be one.

Parameters:

time_bin_indices : dask.array.Array

The start indices of the time bins of shape (utime).

time_bin_counts : dask.array.Array

The counts of unique time in each time bin of shape (utime).

antenna1 : dask.array.Array

Antenna 1 index used to look up the antenna Jones for a particular baseline with shape (row,).

antenna2 : dask.array.Array

Antenna 2 index used to look up the antenna Jones for a particular baseline with shape (row,).

jones : dask.array.Array

Gain solutions of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

vis : dask.array.Array

Data values of shape (row, chan, corr) or (row, chan, corr, corr).

flag : dask.array.Array

Flag data of shape (row, chan, corr) or (row, chan, corr, corr).

Returns

——-

corrected_vis : dask.array.Array

True visibilities of shape (row,chan,corr_1,corr_2)

africanus.calibration.utils.dask.compute_and_corrupt_vis(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, model, uvw, freq, lm)[source]¶

Corrupts time variable component model with arbitrary Jones terms. Currrently only time variable point source models are supported.

Parameters:

time_bin_indices : dask.array.Array

The start indices of the time bins of shape (utime)

time_bin_counts : dask.array.Array

The counts of unique time in each time bin of shape (utime)

antenna1 : dask.array.Array

First antenna indices of shape (row,).

antenna2 : dask.array.Array

Second antenna indices of shape (row,)

jones : dask.array.Array

Gains of shape (utime, ant, chan, dir, corr) or (utime, ant, chan, dir, corr, corr).

model : dask.array.Array

Model image as a function of time with shape (utime, chan, dir, corr) or (utime, chan, dir, corr, corr).

uvw : dask.array.Array

uvw coordinates of shape (row, 3)

Source lm coordinates as a function of time (utime, dir, 2)

Returns:

vis : dask.array.Array

visibilities of shape (row, chan, corr) or (row, chan, corr, corr).

Phase only¶

Numpy¶

`compute_jhr`(time_bin_indices, …)	Computes the residual projected in to gain space.
`compute_jhj`(time_bin_indices, …)	Computes the diagonal of the Hessian required to perform phase-only maximum likelihood calibration.
`compute_jhj_and_jhr`(time_bin_indices, …)	Computes the diagonal of the Hessian and the residual locally projected in to gain space.
`gauss_newton`(time_bin_indices, …[, tol, …])	Performs phase-only maximum likelihood calibration using a Gauss-Newton optimisation algorithm.

africanus.calibration.phase_only.compute_jhr(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, residual, model, flag)[source]¶

Computes the residual projected in to gain space.

Parameters:

time_bin_indices : numpy.ndarray

The start indices of the time bins of shape (utime)

time_bin_counts : numpy.ndarray

The counts of unique time in each time bin of shape (utime)

antenna1 : numpy.ndarray

First antenna indices of shape (row,).

antenna2 : numpy.ndarray

Second antenna indices of shape (row,)

jones : numpy.ndarray

Gain solutions of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

residual : numpy.ndarray

Residual values of shape (row, chan, corr). or (row, chan, corr, corr).

model : numpy.ndarray

Model data values of shape (row, chan, dir, corr) or (row, chan, dir, corr, corr).

flag : numpy.ndarray

Flag data of shape (row, chan, corr) or (row, chan, corr, corr)

Returns:

jhr : numpy.ndarray

The residual projected into gain space shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

africanus.calibration.phase_only.compute_jhj(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, model, flag)[source]¶

Computes the diagonal of the Hessian required to perform phase-only maximum likelihood calibration. Currently assumes scalar or diagonal inputs.

Parameters:

time_bin_indices : numpy.ndarray

The start indices of the time bins of shape (utime)

time_bin_counts : numpy.ndarray

The counts of unique time in each time bin of shape (utime)

antenna1 : numpy.ndarray

First antenna indices of shape (row,).

antenna2 : numpy.ndarray

Second antenna indices of shape (row,)

jones : numpy.ndarray

Gain solutions of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

model : numpy.ndarray

Model data values of shape (row, chan, dir, corr) or (row, chan, dir, corr, corr).

flag : numpy.ndarray

Flag data of shape (row, chan, corr) or (row, chan, corr, corr)

Returns:

jhj : numpy.ndarray

The diagonal of the Hessian of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

africanus.calibration.phase_only.compute_jhj_and_jhr(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, residual, model, flag)[source]¶

Computes the diagonal of the Hessian and the residual locally projected in to gain space.

Parameters:

time_bin_indices : numpy.ndarray

The start indices of the time bins of shape (utime)

time_bin_counts : numpy.ndarray

The counts of unique time in each time bin of shape (utime)

antenna1 : numpy.ndarray

First antenna indices of shape (row,).

antenna2 : numpy.ndarray

Second antenna indices of shape (row,)

jones : numpy.ndarray

Gain solutions of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

residual : numpy.ndarray

Residual values of shape (row, chan, corr). or (row, chan, corr, corr).

model : numpy.ndarray

Model data values of shape (row, chan, dir, corr) or (row, chan, dir, corr, corr).

flag : numpy.ndarray

Flag data of shape (row, chan, corr) or (row, chan, corr, corr)

Returns:

jhj : numpy.ndarray

The diagonal of the Hessian of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

jhr : numpy.ndarray

Residuals projected into signal space of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

africanus.calibration.phase_only.gauss_newton(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, vis, flag, model, weight, tol=0.0001, maxiter=100)[source]¶

Performs phase-only maximum likelihood calibration using a Gauss-Newton optimisation algorithm. Currently only DIAG mode is supported.

Parameters:

time_bin_indices : numpy.ndarray

The start indices of the time bins of shape (utime)

time_bin_counts : numpy.ndarray

The counts of unique time in each time bin of shape (utime)

antenna1 : numpy.ndarray

First antenna indices of shape (row,).

antenna2 : numpy.ndarray

Second antenna indices of shape (row,).

jones : numpy.ndarray

Gain solutions of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

vis : numpy.ndarray

Data values of shape (row, chan, corr) or (row, chan, corr, corr).

flag : numpy.ndarray

Flag data of shape (row, chan, corr) or (row, chan, corr, corr).

model : numpy.ndarray

Model data values of shape (row, chan, dir, corr) or (row, chan, dir, corr, corr).

weight : numpy.ndarray

Weight spectrum of shape (row, chan, corr). If the channel axis is missing weights are duplicated for each channel.

tol: float, optional

The tolerance of the solver. Defaults to 1e-4.

maxiter: int, optional

The maximum number of iterations. Defaults to 100.

Returns:

gains : numpy.ndarray

Gain solutions of shape (time, ant, chan, dir, corr) or shape (time, ant, chan, dir, corr, corr)

jhj : numpy.ndarray

The diagonal of the Hessian of shape (time, ant, chan, dir, corr) or shape (time, ant, chan, dir, corr, corr)

jhr : numpy.ndarray

Residuals projected into gain space of shape (time, ant, chan, dir, corr) or shape (time, ant, chan, dir, corr, corr).

k: int

Number of iterations (will equal maxiter if not converged)

Dask¶

`compute_jhr`(time_bin_indices, …)	Computes the residual projected in to gain space.
`compute_jhj`(time_bin_indices, …)	Computes the diagonal of the Hessian required to perform phase-only maximum likelihood calibration.

africanus.calibration.phase_only.dask.compute_jhr(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, residual, model, flag)[source]¶

Computes the residual projected in to gain space.

Parameters:

time_bin_indices : dask.array.Array

The start indices of the time bins of shape (utime)

time_bin_counts : dask.array.Array

The counts of unique time in each time bin of shape (utime)

antenna1 : dask.array.Array

First antenna indices of shape (row,).

antenna2 : dask.array.Array

Second antenna indices of shape (row,)

jones : dask.array.Array

Gain solutions of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

residual : dask.array.Array

Residual values of shape (row, chan, corr). or (row, chan, corr, corr).

model : dask.array.Array

Model data values of shape (row, chan, dir, corr) or (row, chan, dir, corr, corr).

flag : dask.array.Array

Flag data of shape (row, chan, corr) or (row, chan, corr, corr)

Returns:

jhr : dask.array.Array

The residual projected into gain space shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

africanus.calibration.phase_only.dask.compute_jhj(time_bin_indices, time_bin_counts, antenna1, antenna2, jones, model, flag)[source]¶

Computes the diagonal of the Hessian required to perform phase-only maximum likelihood calibration. Currently assumes scalar or diagonal inputs.

Parameters:

time_bin_indices : dask.array.Array

The start indices of the time bins of shape (utime)

time_bin_counts : dask.array.Array

The counts of unique time in each time bin of shape (utime)

antenna1 : dask.array.Array

First antenna indices of shape (row,).

antenna2 : dask.array.Array

Second antenna indices of shape (row,)

jones : dask.array.Array

Gain solutions of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

model : dask.array.Array

Model data values of shape (row, chan, dir, corr) or (row, chan, dir, corr, corr).

flag : dask.array.Array

Flag data of shape (row, chan, corr) or (row, chan, corr, corr)

Returns:

jhj : dask.array.Array

The diagonal of the Hessian of shape (time, ant, chan, dir, corr) or (time, ant, chan, dir, corr, corr).

Linear Algebra¶

This module contains specialised linear algebra tools that are not currently available in the python standard scientific libraries.

Kronecker tools¶

A kronecker matrix is matrix that can be written as a kronecker matrix of the individual matrices i.e.

\[\begin{split}K = K_0 \\otimes K_1 \\otimes K_2 \\otimes \\cdots\end{split}\]

Matrices which exhibit this structure can exploit properties of the kronecker product to avoid explicitly expanding the matrix $K$. This module implements some common linear algebra operations which leverages this property for computational gains and a reduced memory footprint.

Numpy¶

`kron_matvec`(A, b)	Computes the matrix vector product of a kronecker matrix in linear time.
`kron_cholesky`(A)	Computes the Cholesky decomposition of a kronecker matrix as a kronecker matrix of Cholesky factors.

africanus.linalg.kron_matvec(A, b)[source]¶

Computes the matrix vector product of a kronecker matrix in linear time. Assumes A consists of kronecker product of square matrices.

Parameters:

A : numpy.ndarray

An array of arrays holding matrices [K0, K1, …] where $A = K_0 \otimes K_1 \otimes \cdots$

b : numpy.ndarray

The right hand side vector

Returns:

The result of A.dot(b)

africanus.linalg.kron_cholesky(A)[source]¶

Computes the Cholesky decomposition of a kronecker matrix as a kronecker matrix of Cholesky factors.

Parameters:

A : numpy.ndarray

An array of arrays holding matrices [K0, K1, …] where $A = K_0 \otimes K_1 \otimes \cdots$

Returns:

L : numpy.ndarray

An array of arrays holding matrices [L0, L1, …] where $L = L_0 \otimes L_1 \otimes \cdots$ and each Li = cholesky(Ki)

Gaussian processes¶

This module provides a collection of tools that are useful when performing Gaussian process regression.

Numpy¶

`abs_diff`(x, xp)	Gets matrix of differences between $D$-dimensional vectors x and xp i.e.
`exponential_squared`(x, xp, sigmaf, l[, pspec])	Create exponential squared covariance function between $D$ dimensional vectors $x$ and $x_p$ i.e.

africanus.gps.abs_diff(x, xp)[source]¶

Gets matrix of differences between $D$-dimensional vectors x and xp i.e.

\[X_{ij} = |x_i - x_j|\]

Parameters:

Array of inputs of shape (N, D).

xp : numpy.ndarray

Array of inputs of shape (Np, D).

Returns:

XX : numpy.ndarray

Array of differences of shape (N, Np).

africanus.gps.exponential_squared(x, xp, sigmaf, l, pspec=False)[source]¶

Create exponential squared covariance function between $D$ dimensional vectors $x$ and $x_p$ i.e.

\[k(x, x_p) = \sigma_f^2 \exp\left(-\frac{(x-x_p)^2}{2l^2}\right)\]

Parameters: