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 selfcalibration.
Third generation calibration (3GC): using a partially incomplete sky model to perform direction dependent calibration. Also known as direction dependent selfcalibration.
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 diagdiag
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¶

Corrupts model visibilities with arbitrary Jones terms. 

Computes residual visibilities given model visibilities and gains solutions. 

Apply inverse of direction independent gains to visibilities to generate corrected visibilities. 

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)
.
 time_bin_indices
 Returns
 vis
numpy.ndarray
visibilities of shape
(time, ant, chan, dir, corr)
or(time, ant, chan, dir, corr, corr)
.
 vis
 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)
.
 time_bin_indices
 Returns
 residual
numpy.ndarray
Residual visibilities of shape
(time, ant, chan, dir, corr)
or(time, ant, chan, dir, corr, corr)
.
 residual
 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 nontrivial 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)
 time_bin_indices
 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)
 lm
numpy.ndarray
Source lm coordinates as a function of time
(utime, dir, 2)
 time_bin_indices
 Returns
 vis
numpy.ndarray
visibilities of shape
(row, chan, corr)
or(row, chan, corr, corr)
.
 vis
Dask¶

Corrupts model visibilities with arbitrary Jones terms. 

Computes residual visibilities given model visibilities and gains solutions. 

Apply inverse of direction independent gains to visibilities to generate corrected visibilities. 

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)
.
 time_bin_indices
 Returns
 vis
dask.array.Array
visibilities of shape
(time, ant, chan, dir, corr)
or(time, ant, chan, dir, corr, corr)
.
 vis
 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)
.
 time_bin_indices
 Returns
 residual
dask.array.Array
Residual visibilities of shape
(time, ant, chan, dir, corr)
or(time, ant, chan, dir, corr, corr)
.
 residual
 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 nontrivial 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)
 time_bin_indices
 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)
 lm
dask.array.Array
Source lm coordinates as a function of time
(utime, dir, 2)
 time_bin_indices
 Returns
 vis
dask.array.Array
visibilities of shape
(row, chan, corr)
or(row, chan, corr, corr)
.
 vis
Phase only¶
Numpy¶

Computes the residual projected in to gain space. 

Computes the diagonal of the Hessian required to perform phaseonly maximum likelihood calibration. 

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

Performs phaseonly maximum likelihood calibration using a GaussNewton 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)
 time_bin_indices
 Returns
 jhr
numpy.ndarray
The residual projected into gain space shape
(time, ant, chan, dir, corr)
or(time, ant, chan, dir, corr, corr)
.
 jhr
 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 phaseonly 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)
 time_bin_indices
 Returns
 jhj
numpy.ndarray
The diagonal of the Hessian of shape
(time, ant, chan, dir, corr)
or(time, ant, chan, dir, corr, corr)
.
 jhj
 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)
 time_bin_indices
 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)
.
 jhj
 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 phaseonly maximum likelihood calibration using a GaussNewton 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 1e4.
 maxiter: int, optional
The maximum number of iterations. Defaults to 100.
 time_bin_indices
 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)
 gains
Dask¶

Computes the residual projected in to gain space. 

Computes the diagonal of the Hessian required to perform phaseonly 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)
 time_bin_indices
 Returns
 jhr
dask.array.Array
The residual projected into gain space shape
(time, ant, chan, dir, corr)
or(time, ant, chan, dir, corr, corr)
.
 jhr
 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 phaseonly 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)
 time_bin_indices
 Returns
 jhj
dask.array.Array
The diagonal of the Hessian of shape
(time, ant, chan, dir, corr)
or(time, ant, chan, dir, corr, corr)
.
 jhj