GainTable
- class ska_sdp_datamodels.calibration.GainTable(data_vars=None, coords=None, attrs=None)[source]
Bases:
DatasetContainer for calibration solutions; a GainTable instance implicitly corresponds to a Visibility instance being calibrated. GainTable wraps a collection of either:
complex-valued scalar gains, if dealing with pure Stokes I visibilities.
2x2 complex-valued Jones matrices otherwise.
GainTable currently serves calibration processing functions that rely on the concept of model visibilities, which are related to observed visibilities and Jones matrices as follows:
\(V^{\mathrm{obs}}_{pq} = J_p V^{\mathrm{model}}_{pq} J_q^H\)
where p, q are antenna indices, \(J_k\) denotes the Jones matrix for antenna k, and the H superscript is Hermitian transpose. For scalar visibilities and gains \(g_k\), this can be rewritten as
\(V^{\mathrm{obs}}_{pq} = g_p g_q^* V^{\mathrm{model}}_{pq}\)
Coordinates
time: time centroids of solutions, in seconds elapsed (on the UTC scale) since the MJD reference epoch,
[ntimes].antenna: integer antenna indices starting at 0,
[nants]frequency: frequency centroids of solutions in Hz,
[nchan]receptor1: polarisation hands of measured data polarisation,
[nrec]. Most likely['X', 'Y']or['I'].receptor2: polarisation hands of ideal/model data polarisation,
[nrec]
The idea of allowing two different receptor frames is explained in: https://confluence.skatelescope.org/display/SE/Notes+on+receptor+frames
TODO (Opinionated comment, VM): However, GainTable represents Jones matrices, and the application of a Jones matrix by itself on a voltage/electric field vector cannot change the polarisation basis in which it is expressed (e.g. linear or circular). Jones matrices are a representation of a linear function in one specific vector basis, in which both the input and output vectors must be expressed (which here means receptor1 = receptor2 by definition). Basis changes matrices represent, mathematically speaking, a distinct operator.
See Smirnov 2011, especially section 6.3: https://arxiv.org/pdf/1101.1764.pdf
I’d argue that trying to merge the two concepts of Jones matrix and basis change matrix inside the same class is incorrect, and would be over-engineering even if it was. There isn’t, and likely won’t be a use case for this, since both SKA-Mid and Low have linearly polarised receptors, giving us a privileged base in which to work. Leaving this (admittedly opinionated) notice until discussed and settled with relevant parties.
Data variables
gain: scalar gains or Jones matrices, complex-valued
[ntimes, nants, nchan, nrec, nrec].nrec=2if storing Jones matrices,nrec=1if storing complex gains.weight: “gain weights”, TODO: precise meaning and purpose under investigation, real-valued with same shape as
gain. Previously documented as “The weight is usually that output from gain solvers”.residual: fit residuals returned by the gain solver, real-valued
[ntimes, nchan, nrec, nrec]datetime: time centroids of solutions, in np.datetime64 format,
[ntimes]. Effectively a copy of the “time” coordinate but with a different representation.interval: length of time for which solutions are valid in seconds,
[ntimes]
Attributes
jones_type: capital letter denoting the Jones term this GainTable represents.
phasecentre: Phase centre coordinates as an astropy SkyCoord object.
configuration: Array configuration as a Configuration object.
receptor_frame1: ReceptorFrame for measured data.
receptor_frame2: ReceptorFrame for model data.
data_model: name of this class, used internally for saving to / loading from files.
Here is an example:
<xarray.GainTable> Dimensions: (antenna: 115, frequency: 3, receptor1: 2, receptor2: 2, time: 3) Coordinates: * time (time) float64 5.085e+09 5.085e+09 5.085e+09 * antenna (antenna) int64 0 1 2 3 4 5 6 7 ... 113 114 * frequency (frequency) float64 1e+08 1.05e+08 1.1e+08 * receptor1 (receptor1) <U1 'X' 'Y' * receptor2 (receptor2) <U1 'X' 'Y' Data variables: gain (time, antenna, frequency, receptor1, receptor2) complex128 (0... weight (time, antenna, frequency, receptor1, receptor2) float64 1.0 .... residual (time, frequency, receptor1, receptor2) float64 0.0 0.0 ... 0.0 interval (time) float32 99.72697 99.72697 99.72697 datetime (time) datetime64[ns] 2000-01-01T03:54:07.843184299 ... 2000-0... Attributes: data_model: GainTable receptor_frame1: ReceptorFrame object receptor_frame2: ReceptorFrame object phasecentre: <SkyCoord (ICRS): (ra, dec) in deg> configuration: <xarray.Configuration> Dimensions: (id: 115 etc.) jones_type: B
Methods Summary
constructor([gain, time, interval, weight, ...])Create a GainTable instance directly from numpy arrays.
copy([deep, data, zero])Copy GainTable
Methods Documentation
- classmethod constructor(gain: ndarray[Any, dtype[_ScalarType_co]] | None = None, time: ndarray[Any, dtype[_ScalarType_co]] | None = None, interval: ndarray[Any, dtype[_ScalarType_co]] | None = None, weight: ndarray[Any, dtype[_ScalarType_co]] | None = None, residual: ndarray[Any, dtype[_ScalarType_co]] | None = None, frequency: ndarray[Any, dtype[_ScalarType_co]] | None = None, receptor_frame: ReceptorFrame | Sequence[ReceptorFrame] | None = None, phasecentre: SkyCoord | None = None, configuration: Configuration | None = None, jones_type: Literal['T', 'G', 'B'] = 'T')[source]
Create a GainTable instance directly from numpy arrays.
- Parameters:
gain (ndarray or None, optional) – Complex gains [ntimes, nants, nchan, nrec, nrec]
time (ndarray or None, optional) – Centroids of solutions, in seconds elapsed since the MJD reference epoch [ntimes]
interval (ndarray or None, optional) – Intervals of validity in seconds [ntimes]
weight (ndarray or None, optional) – Weights of gains [ntimes, nants, nchan, nrec, nrec]
residual (ndarray or None, optional) – Residuals of fit [ntimes, nchan, nrec, nrec]
frequency (ndarray or None, optional) – Channel frequencies in Hz [nchan]
receptor_frame (ReceptorFrame or sequence of two ReceptorFrames or None, optional) – Measured and ideal (model) data receptor frames; equivalent to two sides of the Jones matrix. Receptor1 stands for measured data polarisation; Receptor2 stands for ideal/model data polarisation. If None, use a linear receptor frame for both receptor1 and receptor2. If ReceptorFrame instance, use it for both receptor1 and receptor2. If two-element sequence, interpret as [receptor1, receptor2]. See also: https://confluence.skatelescope.org/display/SE/Notes+on+receptor+frames
phasecentre (astropy.coord.SkyCoord or None, optional) – Phase centre coordinates
configuration (Configuration or None, optional) – Configuration object describing the array configuration
jones_type (str, optional) – Capital letter denoting the Jones term this GainTable will represent.