PHASE_DELAY_DOCS = DocstringTemplate(r"""
Computes the phase delay (K) term:
.. math::
& {\Large e^{-2 \pi i (u l + v m + w (n - 1))} }
& \textrm{where } n = \sqrt{1 - l^2 - m^2}
Notes
-----
Corresponds to the complex exponential of the `Van Cittert-Zernike Theorem
<https://en.wikipedia.org/wiki/Van_Cittert%E2%80%93Zernike_theorem_>`_.
`MeqTrees
<https://github.com/ska-sa/meqtrees-timba/blob/
6a7e873d4d1fe538981dec5851418cbd371b8388/MeqNodes/src/PSVTensor.cc#L314_>`_
uses a positive sign convention and so any UVW coordinates must be inverted
in order for their phase delay terms (and therefore visibilities) to agree.
Parameters
----------
lm : $(array_type)
LM coordinates of shape :code:`(source, 2)` with
L and M components in the last dimension.
uvw : $(array_type)
UVW coordinates of shape :code:`(row, 3)` with
U, V and W components in the last dimension.
frequency : $(array_type)
frequencies of shape :code:`(chan,)`
Returns
-------
complex_phase : $(array_type)
complex of shape :code:`(source, row, chan)`
""")
GAUSSIAN_DOCS = DocstringTemplate(r"""
Computes the Gaussian Shape Function.
.. math::
& \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)}
where:
- :math:`u` and :math:`v` are the UV coordinates and
:math:`\lambda` the frequency.
- :math:`e_{maj}` and :math:`e_{min}` are the major and minor axes
and :math:`\alpha` the position angle.
Parameters
----------
uvw : $(array_type)
UVW coordinates of shape :code:`(row, 3)`
frequency : $(array_type)
frequencies of shape :code:`(chan,)`
shape_param : $(array_type)
Gaussian Shape Parameters of shape :code:`(source, 3)`
where the second dimension contains the
`(emajor, eminor, angle)` parameters describing
the shape of the Gaussian
Returns
-------
gauss_shape : $(array_type)
Shape parameters of shape :code:`(source, row, chan)`
""")
SPECTRA_DOCS = DocstringTemplate(r"""
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:
.. math::
& 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) \\
See the `WSClean Component List
<https://sourceforge.net/p/wsclean/wiki/ComponentList/>`_
for further details.
Parameters
----------
I : $(array_type)
flux density in Janskys at the reference frequency
of shape :code:`(source,)`
coeffs : $(array_type)
Polynomial coefficients for each source of
shape :code:`(source, comp)`
log_poly : $(array_type) or bool
boolean array of shape :code:`(source, )`
indicating whether logarithmic (True) or ordinary (False)
polynomials should be used.
ref_freq : $(array_type)
Source reference frequencies of shape :code:`(source,)`
frequency : $(array_type)
frequencies of shape :code:`(chan,)`
See Also
--------
africanus.model.wsclean.load
Returns
-------
spectral_model : $(array_type)
Spectral Model of shape :code:`(source, chan)`
""")
PREDICT_DOCS = DocstringTemplate(r"""
Multiply Jones terms together to form model visibilities according
to the following formula:
.. math::
V_{pq} = G_{p} \left(
B_{pq} + \sum_{s} A_{ps} X_{pqs} A_{qs}^H
\right) G_{q}^H
where for antenna :math:`p` and :math:`q`, and source :math:`s`:
- :math:`B_{{pq}}` represent base coherencies.
- :math:`E_{{ps}}` represents Direction-Dependent Jones terms.
- :math:`X_{{pqs}}` represents a coherency matrix (per-source).
- :math:`G_{{p}}` represents Direction-Independent Jones terms.
Generally, :math:`E_{ps}`, :math:`G_{p}`, :math:`X_{pqs}`
should be formed by using the `RIME API <rime-api-anchor_>`_ functions
and combining them together with :func:`~numpy.einsum`.
**Please read the Notes**
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.
$(extra_notes)
Parameters
----------
time_index : $(array_type)
Time index used to look up the antenna Jones index
for a particular baseline.
shape :code:`(row,)`.
antenna1 : $(array_type)
Antenna 1 index used to look up the antenna Jones
for a particular baseline.
with shape :code:`(row,)`.
antenna2 : $(array_type)
Antenna 2 index used to look up the antenna Jones
for a particular baseline.
with shape :code:`(row,)`.
dde1_jones : $(array_type), optional
:math:`A_{ps}` Direction-Dependent Jones terms for the first antenna.
shape :code:`(source,time,ant,chan,corr_1,corr_2)`
source_coh : $(array_type), optional
:math:`X_{pqs}` Direction-Dependent Coherency matrix for the baseline.
with shape :code:`(source,row,chan,corr_1,corr_2)`
dde2_jones : $(array_type), optional
:math:`A_{qs}` Direction-Dependent Jones terms for the second antenna.
shape :code:`(source,time,ant,chan,corr_1,corr_2)`
die1_jones : $(array_type), optional
:math:`G_{ps}` Direction-Independent Jones terms for the
first antenna of the baseline.
with shape :code:`(time,ant,chan,corr_1,corr_2)`
base_vis : $(array_type), optional
:math:`B_{pq}` base visibilities, added to source coherency summation
*before* multiplication with `die1_jones` and `die2_jones`.
shape :code:`(row,chan,corr_1,corr_2)`.
die2_jones : $(array_type), optional
:math:`G_{ps}` Direction-Independent Jones terms for the
second antenna of the baseline.
with shape :code:`(time,ant,chan,corr_1,corr_2)`
$(extra_args)
Returns
-------
visibilities : $(array_type)
Model visibilities of shape :code:`(row,chan,corr_1,corr_2)`
""")
COMPUTE_AND_CORRUPT_VIS_DOCS = DocstringTemplate("""
Corrupts time variable component model with arbitrary
Jones terms. Currrently only time variable point source
models are supported.
Parameters
----------
time_bin_indices : $(array_type)
The start indices of the time bins
of shape :code:`(utime)`
time_bin_counts : $(array_type)
The counts of unique time in each
time bin of shape :code:`(utime)`
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`.
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
jones : $(array_type)
Gains of shape :code:`(utime, ant, chan, dir, corr)`
or :code:`(utime, ant, chan, dir, corr, corr)`.
model : $(array_type)
Model image as a function of time with shape
:code:`(utime, chan, dir, corr)` or
:code:`(utime, chan, dir, corr, corr)`.
uvw : $(array_type)
uvw coordinates of shape :code:`(row, 3)`
lm : $(array_type)
Source lm coordinates as a function of time
:code:`(utime, dir, 2)`
Returns
-------
vis : $(array_type)
visibilities of shape
:code:`(row, chan, corr)`
or :code:`(row, chan, corr, corr)`.
""")
BEAM_CUBE_DOCS = DocstringTemplate(r"""
Evaluates Direction Dependent Effects along a source's path
by interpolating the values of a complex beam cube
at the source location.
Notes
-----
1. Sources are clamped to the provided `beam_lm_extents`.
2. Frequencies outside the cube (i.e. outside beam_freq_map)
introduce linear scaling to the lm coordinates of a source.
Parameters
----------
beam : $(array_type)
Complex beam cube of
shape :code:`(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 : $(array_type)
lm extents of the beam cube of shape :code:`(2, 2)`.
``[[lower_l, upper_l], [lower_m, upper_m]]``.
beam_freq_map : $(array_type)
Beam frequency map of shape :code:`(beam_nud,)`.
This array is used to define interpolation along
the :code:`(chan,)` dimension.
lm : $(array_type)
Source lm coordinates of shape :code:`(source, 2)`.
These coordinates are:
1. Scaled if the associated frequency lies outside the beam cube.
2. Offset by pointing errors: ``point_errors``
3. Rotated by parallactic angles: ``parallactic_angles``.
4. Scaled by antenna scaling factors: ``antenna_scaling``.
parallactic_angles : $(array_type)
Parallactic angles of shape :code:`(time, ant)`.
point_errors : $(array_type)
Pointing errors of shape :code:`(time, ant, chan, 2)`.
antenna_scaling : $(array_type)
Antenna scaling factors of shape :code:`(ant, chan, 2)`
frequency : $(array_type)
Frequencies of shape :code:`(chan,)`.
Returns
-------
ddes : $(array_type)
Direction Dependent Effects of shape
:code:`(source, time, ant, chan, corr, corr)`
""")
PHASE_DELAY_DOCS = DocstringTemplate(r"""
Computes the phase delay (K) term:
.. math::
& {\Large e^{-2 \pi i (u l + v m + w (n - 1))} }
& \textrm{where } n = \sqrt{1 - l^2 - m^2}
Notes
-----
Corresponds to the complex exponential of the `Van Cittert-Zernike Theorem
<https://en.wikipedia.org/wiki/Van_Cittert%E2%80%93Zernike_theorem_>`_.
`MeqTrees
<https://github.com/ska-sa/meqtrees-timba/blob/
6a7e873d4d1fe538981dec5851418cbd371b8388/MeqNodes/src/PSVTensor.cc#L314_>`_
uses the CASA sign convention.
Parameters
----------
lm : $(array_type)
LM coordinates of shape :code:`(source, 2)` with
L and M components in the last dimension.
uvw : $(array_type)
UVW coordinates of shape :code:`(row, 3)` with
U, V and W components in the last dimension.
frequency : $(array_type)
frequencies of shape :code:`(chan,)`
convention : {'fourier', 'casa'}
Uses the :math:`e^{-2 \pi \mathit{i}}` sign convention
if ``fourier`` and :math:`e^{2 \pi \mathit{i}}` if
``casa``.
Returns
-------
complex_phase : $(array_type)
complex of shape :code:`(source, row, chan)`
""")
:code:`(dim_1, ..., dim_n, icorr_1, ..., icorr_m)`
input_schema : list of str or int
A schema describing the :code:`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 :code:`ocorr_1, ..., ocorr_n`
dimension of the return value.
Returns
-------
result : $(array_type)
Result of shape :code:`(dim_1, ..., dim_n, ocorr_1, ..., ocorr_m)`
The type may be floating point or promoted to complex
depending on the combinations in ``output``.
"""
# Fill in the STOKES TYPES
_map_str = ", ".join(["%s: %d" % (t, i) for i, t in enumerate(STOKES_TYPES)])
_map_str = "{{ " + _map_str + " }}"
# Indent must match docstrings
_map_str = fill(_map_str, initial_indent='', subsequent_indent=' ' * 8)
CONVERT_DOCS = DocstringTemplate(CONVERT_DOCS.format(stokes_type_map=_map_str))
del _map_str
try:
convert.__doc__ = CONVERT_DOCS.substitute(
array_type=":class:`numpy.ndarray`")
except AttributeError:
pass
RADEC_TO_LMN_DOCS = DocstringTemplate(r"""
Converts Right-Ascension/Declination coordinates in radians
to a Direction Cosine lm coordinates, relative to the Phase Centre.
.. math::
:nowrap:
\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 :math:`\Delta \alpha = \alpha - \alpha 0` is the difference between
the Right Ascension of each coordinate and the phase centre and
:math:`\delta 0` is the Declination of the phase centre.
Parameters
----------
radec : $(array_type)
radec coordinates of shape :code:`(coord, 2)`
where Right-Ascension and Declination are in the
last 2 components, respectively.
phase_centre : $(array_type), optional
radec coordinates of the Phase Centre.
Shape :code:`(2,)`
Returns
-------
$(array_type)
lm Direction Cosines of shape :code:`(coord, $(lm_components))`
""")
FEED_ROTATION_DOCS = DocstringTemplate(r"""
Computes the 2x2 feed rotation (L) matrix
from the ``parallactic_angles``.
.. math::
\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}
Parameters
----------
parallactic_angles : $(array_type)
floating point parallactic angles. Of shape
:code:`(pa0, pa1, ..., pan)`.
feed_type : {'linear', 'circular'}
The type of feed
Returns
-------
feed_matrix : $(array_type)
Feed rotation matrix of shape :code:`(pa0, pa1,...,pan,2,2)`
""")
RESIDUAL_DOCS = DocstringTemplate(
r"""
Compute residual image given a model and visibilities using ducc
degridder i.e.
.. math::
I^R = R^\dagger \Sigma^{-1}(V - Rx)
where :math:`R` is an implicit degridding operator, :math:`V`
denotes visibilities of shape :code:`(row, chan)` and
:math:`x` is the image of shape :code:`(band, nx, ny)`.
The number of imaging bands :code:`(band)` must
be less than or equal to the number of channels
:code:`(chan)` at which the data were obtained.
The mapping from :code:`(chan)` to :code:`(band)` is described
by :code:`freq_bin_idx` and :code:`freq_bin_counts` as
described below.
Note that, if the gridding and degridding operators both apply
the square root of the imaging weights then the visibilities
that are passed in should be pre-whitened. In this case the
function computes
.. math::
I^R = R^\dagger \Sigma^{-\frac{1}{2}}(\tilde{V}
- \Sigma^{-\frac{1}{2}}Rx)
which is identical to the above expression if
:math:`\tilde{V} = \Sigma^{-\frac{1}{2}}V`.
Parameters
----------
uvw : $(array_type)
uvw coordinates at which visibilities were
obtained with shape :code:`(row, 3)`.
freq : $(array_type)
Observational frequencies of shape :code:`(chan,)`.
model : $(array_type)
Model image to degrid of shape :code:`(band, nx, ny)`.
vis : $(array_type)
Visibilities of shape :code:`(row,chan)`.
weights : $(array_type)
Imaging weights of shape :code:`(row, chan)`.
freq_bin_idx : $(array_type)
Starting indices of frequency bins for each imaging
band of shape :code:`(band,)`.
freq_bin_counts : $(array_type)
The number of channels in each imaging band of shape :code:`(band,)`.
cell : float
The cell size of a pixel along the :math:`x` direction in radians.
flag: $(array_type), optional
Flags of shape :code:`(row,chan)`. Will only process visibilities
for which flag!=0
celly : float, optional
The cell size of a pixel along the :math:`y` direction in radians.
By default same as cell size along :math:`x` direction.
nu : int, optional
The number of pixels in the padded grid along the :math:`x` direction.
Chosen automatically by default.
nv : int, optional
The number of pixels in the padded grid along the :math:`y` direction.
Chosen automatically by default.
epsilon : float, optional
The precision of the gridder with respect to the direct Fourier
transform. By deafult, this is set to :code:`1e-5` for single
precision and :code:`1e-7` for double precision.
nthreads : int, optional
The number of threads to use. Defaults to one.
do_wstacking : bool, optional
Whether to correct for the w-term or not. Defaults to True
double_accum : bool, optional
If true ducc will accumulate in double precision regardless of
the input type.
Returns
-------
residual : $(array_type)
Residual image corresponding to :code:`model` of shape
:code:`(band, nx, ny)`.
""")
SPECTRAL_MODEL_DOC = DocstringTemplate(r"""
Compute a spectral model, per polarisation.
.. math::
:nowrap:
\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 : $(array_type)
Stokes parameters of shape :code:`(source,)` or :code:`(source, pol)`.
If a ``pol`` dimension is present, then it must also be present on ``spi``.
spi : $(array_type)
Spectral index of shape :code:`(source, spi-comps)`
or :code:`(source, spi-comps, pol)`.
ref_freq : $(array_type)
Reference frequencies of shape :code:`(source,)`
frequencies : $(array_type)
Frequencies of shape :code:`(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 : $(array_type)
Spectral Model of shape :code:`(source, chan)` or
:code:`(source, chan, pol)`.
""")
WSCLEAN_PREDICT_DOCS = DocstringTemplate("""
Predict visibilities from a `WSClean sky model
<https://sourceforge.net/p/wsclean/wiki/ComponentList/>`_.
Parameters
----------
uvw : $(array_type)
UVW coordinates of shape :code:`(row, 3)`
lm : $(array_type)
Source LM coordinates of shape :code:`(source, 2)`, in radians.
Derived from the ``Ra`` and ``Dec`` fields.
source_type : $(array_type)
Strings defining the source type of shape :code:`(source,)`.
Should be either ``"POINT"`` or ``"GAUSSIAN"``.
Contains the ``Type`` field.
flux : $(array_type)
Source flux of shape :code:`(source,)`.
Contains the ``I`` field.
coeffs : $(array_type)
Source Polynomial coefficients of shape :code:`(source, coeffs)`.
Contains the ``SpectralIndex`` field.
log_poly : $(array_type)
Source polynomial type of shape :code:`(source,)`.
If True, logarithmic polynomials are used.
If False, standard polynomials are used.
Contains the ``LogarithmicSI`` field.
ref_freq : $(array_type)
Source Reference frequency of shape :code:`(source,)`.
Contains the ``ReferenceFrequency`` field.
gauss_shape : $(array_type)
Gaussian shape parameters of shape :code:`(source, 3)`
used when the corresponding ``source_type`` is ``"GAUSSIAN"``.
The 3 components should contain the ``MajorAxis``, ``MinorAxis``
and ``Orientation`` fields in radians, respectively.
frequency : $(array_type)
Frequency of shape :code:`(chan,)`.
Returns
-------
visibilities : $(array_type)
Complex visibilities of shape :code:`(row, chan, 1)`
""")
CORRUPT_VIS_DOCS = DocstringTemplate("""
Corrupts model visibilities with arbitrary
Jones terms.
Parameters
----------
time_bin_indices : $(array_type)
The start indices of the time bins
of shape :code:`(utime)`
time_bin_counts : $(array_type)
The counts of unique time in each
time bin of shape :code:`(utime)`
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`.
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
jones : $(array_type)
Gains of shape :code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
model : $(array_type)
Model data values of shape :code:`(row, chan, dir, corr)`
or :code:`(row, chan, dir, corr, corr)`.
Returns
-------
vis : $(array_type)
visibilities of shape
:code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
""")
AVERAGING_DOCS = DocstringTemplate("""
Averages in time and channel.
Parameters
----------
time : $(array_type)
Time values of shape :code:`(row,)`.
interval : $(array_type)
Interval values of shape :code:`(row,)`.
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
time_centroid : $(array_type), optional
Time centroid values of shape :code:`(row,)`
exposure : $(array_type), optional
Exposure values of shape :code:`(row,)`
flag_row : $(array_type), optional
Flagged rows of shape :code:`(row,)`.
uvw : $(array_type), optional
UVW coordinates of shape :code:`(row, 3)`.
weight : $(array_type), optional
Weight values of shape :code:`(row, corr)`.
sigma : $(array_type), optional
Sigma values of shape :code:`(row, corr)`.
chan_freq : $(array_type), optional
Channel frequencies of shape :code:`(chan,)`.
chan_width : $(array_type), optional
Channel widths of shape :code:`(chan,)`.
effective_bw : $(array_type), optional
Effective channel bandwidth of shape :code:`(chan,)`.
resolution : $(array_type), optional
Effective channel resolution of shape :code:`(chan,)`.
vis : $(array_type), optional
Visibility data of shape :code:`(row, chan, corr)`.
flag : $(array_type), optional
Flag data of shape :code:`(row, chan, corr)`.
weight_spectrum : $(array_type), optional
Weight spectrum of shape :code:`(row, chan, corr)`.
sigma_spectrum : $(array_type), optional
Sigma spectrum of shape :code:`(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.
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.
Returns
-------
namedtuple
A namedtuple whose entries correspond to the input arrays.
Output arrays will be ``None`` if the inputs were ``None``.
""")
BDA_DOCS = DocstringTemplate("""
Averages in time and channel, dependent on baseline length.
Parameters
----------
time : $(array_type)
Time values of shape :code:`(row,)`.
interval : $(array_type)
Interval values of shape :code:`(row,)`.
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
time_centroid : $(array_type), optional
Time centroid values of shape :code:`(row,)`
exposure : $(array_type), optional
Exposure values of shape :code:`(row,)`
flag_row : $(array_type), optional
Flagged rows of shape :code:`(row,)`.
uvw : $(array_type), optional
UVW coordinates of shape :code:`(row, 3)`.
weight : $(array_type), optional
Weight values of shape :code:`(row, corr)`.
sigma : $(array_type), optional
Sigma values of shape :code:`(row, corr)`.
chan_freq : $(array_type), optional
Channel frequencies of shape :code:`(chan,)`.
chan_width : $(array_type), optional
Channel widths of shape :code:`(chan,)`.
effective_bw : $(array_type), optional
Effective channel bandwidth of shape :code:`(chan,)`.
resolution : $(array_type), optional
Effective channel resolution of shape :code:`(chan,)`.
visibilities : $(array_type) or tuple of $(array_type), optional
Visibility data of shape :code:`(row, chan, corr)`.
Tuples of visibilities arrays may be supplied,
in which case tuples will be output.
flag : $(array_type), optional
Flag data of shape :code:`(row, chan, corr)`.
weight_spectrum : $(array_type), optional
Weight spectrum of shape :code:`(row, chan, corr)`.
sigma_spectrum : $(array_type), optional
Sigma spectrum of shape :code:`(row, chan, corr)`.
max_uvw_dist : float, optional
Maximum UVW distance. Will be inferred from the UVW
coordinates if not supplied.
max_fov : float
Maximum Field of View Radius. Defaults to 3 degrees.
decorrelation : float
Acceptable amount of decorrelation. This is
a floating point value between 0.0 and 1.0.
time_bin_secs : float, optional
Maximum number of seconds worth of data that
can be aggregated into a bin.
Defaults to None in which case the value is only
bounded by the decorrelation factor and the
field of view.
min_nchan : int, optional
Minimum number of channels in an averaged sample.
Useful in cases where imagers expect
at least `min_nchan` channels.
Defaults to 1.
Notes
-----
In all cases arrays starting with :code:`(row, chan)`
and :code:`(row,)` dimensions are respectively averaged
and expanded into a :code:`(rowchan,)` dimension,
as the number of channels varies per output row.
The output namedtuple contains an `offsets` array of
shape :code:`(out_rows + 1,)` encoding the starting
offsets of each output row, as well as a single entry at
the end such that :code:`np.diff(offsets)` produces
the number of channels for each output row.
.. code-block:: python
avg = bda(...)
time = avg.time[avg.offsets[:-1]]
out_chans = np.diff(avg.offsets)
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.
Returns
-------
namedtuple
A namedtuple whose entries correspond to the input arrays.
Output arrays will be ``None`` if the inputs were ``None``.
See the Notes for an explanation of the output formats.
""")
AVERAGING_DOCS = DocstringTemplate("""
Averages in time and channel.
Parameters
----------
time : $(array_type)
Time values of shape :code:`(row,)`.
interval : $(array_type)
Interval values of shape :code:`(row,)`.
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
time_centroid : $(array_type), optional
Time centroid values of shape :code:`(row,)`
exposure : $(array_type), optional
Exposure values of shape :code:`(row,)`
flag_row : $(array_type), optional
Flagged rows of shape :code:`(row,)`.
uvw : $(array_type), optional
UVW coordinates of shape :code:`(row, 3)`.
weight : $(array_type), optional
Weight values of shape :code:`(row, corr)`.
sigma : $(array_type), optional
Sigma values of shape :code:`(row, corr)`.
chan_freq : $(array_type), optional
Channel frequencies of shape :code:`(chan,)`.
chan_width : $(array_type), optional
Channel widths of shape :code:`(chan,)`.
vis : $(array_type), optional
Visibility data of shape :code:`(row, chan, corr)`.
flag : $(array_type), optional
Flag data of shape :code:`(row, chan, corr)`.
weight_spectrum : $(array_type), optional
Weight spectrum of shape :code:`(row, chan, corr)`.
sigma_spectrum : $(array_type), optional
Sigma spectrum of shape :code:`(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 generally be ``None`` if the inputs were ``None``.
""")
PHASE_CALIBRATION_DOCS = DocstringTemplate("""
Performs phase-only maximum likelihood
calibration assuming scalar or diagonal
inputs using Gauss-Newton oprimisation.
Parameters
----------
time_bin_indices : $(array_type)
The start indices of the time bins
of shape :code:`(utime)`
time_bin_counts : $(array_type)
The counts of unique time in each
time bin of shape :code:`(utime)`
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`.
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`.
jones : $(array_type)
Gain solutions of shape :code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
vis : $(array_type)
Data values of shape :code:`(row, chan, corr)`
or :code:`(row, chan, corr, corr)`.
flag : $(array_type)
Flag data of shape :code:`(row, chan, corr)`
or :code:`(row, chan, corr, corr)`.
model : $(array_type)
Model data values of shape :code:`(row, chan, dir, corr)`
or :code:`(row, chan, dir, corr, corr)`.
weight : $(array_type)
Weight spectrum of shape :code:`(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 : $(array_type)
Gain solutions of shape :code:`(time, ant, chan, dir, corr)`
or shape :code:`(time, ant, chan, dir, corr, corr)`
jhj : $(array_type)
The diagonal of the Hessian of shape
:code:`(time, ant, chan, dir, corr)` or shape
:code:`(time, ant, chan, dir, corr, corr)`
jhr : $(array_type)
Residuals projected into gain space
of shape :code:`(time, ant, chan, dir, corr)`
or shape :code:`(time, ant, chan, dir, corr, corr)`.
k : int
Number of iterations (will equal maxiter if
not converged)
""")
time_bin_counts = time_bin_counts.astype(np.int32)
return tuple(row_chunks), time_bin_indices, time_bin_counts
CHECK_TYPE_DOCS = DocstringTemplate("""
Determines which calibration scenario to apply i.e.
DIAG_DIAG, DIAG or COMPLEX2x2.
Parameters
----------
jones : $(array_type)
Jones term of shape :code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`
vis : $(array_type)
Visibility data of shape :code:`(row, chan, corr)`
or :code:`(row, chan, corr, corr)`
vis_type : str
String specifying what kind of visibility we are checking
against. Options are 'vis' or 'model'
Returns
-------
mode : integer
An integer representing the calibration mode.
Options are 0 -> DIAG_DIAG, 1 -> DIAG, 2 -> FULL
""")
try:
check_type.__doc__ = CHECK_TYPE_DOCS.substitute(
array_type=":class:`numpy.ndarray`")
SPI_DOCSTRING = DocstringTemplate(r"""
Computes the spectral indices and the intensity
at the reference frequency of a spectral index model:
.. math::
I(\nu) = I(\nu_0) \left( \frac{\nu}{\nu_0} \right) ^ \alpha
Parameters
----------
data : $(array_type)
array of shape :code:`(comps, chan)`
The noisy data as a function of frequency.
weights : $(array_type)
array of shape :code:`(chan,)`
Inverse of variance on each frequency axis.
freqs : $(array_type)
frequencies of shape :code:`(chan,)`
freq0 : float
Reference frequency
alphai : $(array_type), optional
array of shape :code:`(comps,)`
Initial guess for the alphas. Defaults
to -0.7.
I0i : $(array_type), optional
array of shape :code:`(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 : $(array_type)
array of shape :code:`(4, comps)`
The fitted components arranged
as [alphas, alphavars, I0s, I0vars]
""")
RESIDUAL_VIS_DOCS = DocstringTemplate("""
Computes residual visibilities in place
given model visibilities and gains solutions.
Parameters
----------
time_bin_indices : $(array_type)
The start indices of the time bins
of shape :code:`(utime)`
time_bin_counts : $(array_type)
The counts of unique time in each
time bin of shape :code:`(utime)`
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`.
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
jones : $(array_type)
Gain solutions of shape :code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
vis : $(array_type)
Data values of shape :code:`(row, chan, corr)`.
or :code:`(row, chan, corr, corr)`.
flag : $(array_type)
Flag data of shape :code:`(row, chan, corr)`
or :code:`(row, chan, corr, corr)`
model : $(array_type)
Model data values of shape :code:`(row, chan, dir, corr)`
or :code:`(row, chan, dir, corr, corr)`.
Returns
-------
residual : $(array_type)
Residual visibilities of shape
:code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
""")
RESIDUAL_VIS_DOCS = DocstringTemplate("""
Computes residual visibilities given model
visibilities and gains solutions.
Parameters
----------
time_bin_indices : $(array_type)
The start indices of the time bins
of shape :code:`(utime)`
time_bin_counts : $(array_type)
The counts of unique time in each
time bin of shape :code:`(utime)`
antenna1 : $(array_type)
First antenna indices of shape :code:`(row,)`.
antenna2 : $(array_type)
Second antenna indices of shape :code:`(row,)`
jones : $(array_type)
Gain solutions of shape :code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
vis : $(array_type)
Data values of shape :code:`(row, chan, corr)`.
or :code:`(row, chan, corr, corr)`.
flag : $(array_type)
Flag data of shape :code:`(row, chan, corr)`
or :code:`(row, chan, corr, corr)`
model : $(array_type)
Model data values of shape :code:`(row, chan, dir, corr)`
or :code:`(row, chan, dir, corr, corr)`.
Returns
-------
residual : $(array_type)
Residual visibilities of shape
:code:`(time, ant, chan, dir, corr)`
or :code:`(time, ant, chan, dir, corr, corr)`.
""")
DIRTY_DOCS = DocstringTemplate(r"""
Compute visibility to image mapping using ducc gridder i.e.
.. math::
I^D = R^\dagger \Sigma^{-1} V
where :math:`R^\dagger` is an implicit gridding operator,
:math:`V` denotes visibilities of shape :code:`(row, chan)` and
:math:`I^D` is the dirty image of shape :code:`(band, nx, ny)`.
The number of imaging bands :code:`(band)` must
be less than or equal to the number of channels
:code:`(chan)` at which the data were obtained.
The mapping from :code:`(chan)` to :code:`(band)` is described
by :code:`freq_bin_idx` and :code:`freq_bin_counts` as
described below.
Note that, if self adjoint gridding and degridding operators
are required then :code:`weights` should be the square
root of what is typically referred to as imaging weights and
should also be passed into the degridder.
In this case, the data needs to be pre-whitened.
Parameters
----------
uvw : $(array_type)
uvw coordinates at which visibilities were
obtained with shape :code:`(row, 3)`.
freq : $(array_type)
Observational frequencies of shape :code:`(chan,)`.
vis : $(array_type)
Visibilities of shape :code:`(row,chan)`.
freq_bin_idx : $(array_type)
Starting indices of frequency bins for each imaging
band of shape :code:`(band,)`.
freq_bin_counts : $(array_type)
The number of channels in each imaging band of shape :code:`(band,)`.
cell : float
The cell size of a pixel along the :math:`x` direction in radians.
weights : $(array_type), optional
Imaging weights of shape :code:`(row, chan)`.
flag: $(array_type), optional
Flags of shape :code:`(row,chan)`. Will only process visibilities
for which flag!=0
celly : float, optional
The cell size of a pixel along the :math:`y` direction in radians.
By default same as cell size along :math:`x` direction.
epsilon : float, optional
The precision of the gridder with respect to the direct Fourier
transform. By deafult, this is set to :code:`1e-5` for single
precision and :code:`1e-7` for double precision.
nthreads : int, optional
The number of threads to use. Defaults to one.
If set to zero will use all available cores.
do_wstacking : bool, optional
Whether to correct for the w-term or not. Defaults to True
Returns
-------
model : $(array_type)
Dirty image corresponding to visibilities
of shape :code:`(nband, nx, ny)`.
""")
MODEL_DOCS = DocstringTemplate(r"""
Compute image to visibility mapping using ducc degridder i.e.
.. math::
V = Rx
where :math:`R` is an implicit degridding operator, :math:`V`
denotes visibilities of shape :code:`(row, chan)` and
:math:`x` is the image of shape :code:`(band, nx, ny)`.
The number of imaging bands :code:`(band)` has to
be less than or equal to the number of channels
:code:`(chan)` at which the data were obtained.
The mapping from :code:`(chan)` to :code:`(band)` is described
by :code:`freq_bin_idx` and :code:`freq_bin_counts` as
described below.
There is an option to provide weights during degridding
to cater for self adjoint gridding and degridding operators.
In this case :code:`weights` should actually be the square
root of what is typically referred to as imaging weights.
In this case the degridder computes the whitened model
visibilities i.e.
.. math::
V = \Sigma^{-\frac{1}{2}} R x
where :math:`\Sigma` refers to the inverse of the weights
(i.e. the data covariance matrix when using natural weighting).
Parameters
----------
uvw : $(array_type)
uvw coordinates at which visibilities were
obtained with shape :code:`(row, 3)`.
freq : $(array_type)
Observational frequencies of shape :code:`(chan,)`.
model : $(array_type)
Model image to degrid of shape :code:`(nband, nx, ny)`.
freq_bin_idx : $(array_type)
Starting indices of frequency bins for each imaging
band of shape :code:`(band,)`.
freq_bin_counts : $(array_type)
The number of channels in each imaging band of shape :code:`(band,)`.
cell : float
The cell size of a pixel along the :math:`x` direction in radians.
weights : $(array_type), optional
Imaging weights of shape :code:`(row, chan)`.
flag: $(array_type), optional
Flags of shape :code:`(row,chan)`. Will only process visibilities
for which flag!=0
celly : float, optional
The cell size of a pixel along the :math:`y` direction in radians.
By default same as cell size along :math:`x` direction.
epsilon : float, optional
The precision of the gridder with respect to the direct Fourier
transform. By deafult, this is set to :code:`1e-5` for single
precision and :code:`1e-7` for double precision.
nthreads : int, optional
The number of threads to use. Defaults to one.
If set to zero will use all available cores.
do_wstacking : bool, optional
Whether to correct for the w-term or not. Defaults to True
Returns
-------
vis : $(array_type)
Visibilities corresponding to :code:`model` of shape
:code:`(row,chan)`.
""")