Welcome to Codex Africanus’s documentation!¶
Installation¶
Stable release¶
To install Codex Africanus, run this command in your terminal:
$ pip install codex-africanus
This is the preferred method to install Codex Africanus, as it will always install the most recent stable release.
If you don’t have pip installed, this Python installation guide can guide you through the process.
By default, Codex Africanus will install with a minimal set of dependencies, numpy and numba.
Further functionality can be enabled by installing extra requirements as follows:
$ pip install codex-africanus[dask]
$ pip install codex-africanus[scipy]
$ pip install codex-africanus[astropy]
$ pip install codex-africanus[python-casacore]
To install the complete set of dependencies for the CPU:
$ pip install codex-africanus[complete]
To install the complete set of dependencies including CUDA:
$ pip install codex-africanus[complete-cuda]
From sources¶
The sources for Codex Africanus can be downloaded from the Github repo.
You can either clone the public repository:
$ git clone git://github.com/ska-sa/codex-africanus
Or download the tarball:
$ curl -OL https://github.com/ska-sa/codex-africanus/tarball/master
Once you have a copy of the source, you can install it with:
$ python setup.py install
Command Line Utilities¶
The following command line utilities are installed. Run each utility’s help for further information.
$ utility --help
plot-filter¶
Plots convolution filters.
plot-taper¶
Plots tapers associated with convolution filters.
API¶
Radio Interferometer Measurement Equation¶
Functions used to compute the terms of the Radio Interferometer Measurement Equation (RIME). It describes the response of an interferometer to a sky model.
where for antenna \(p\) and \(q\), and source \(s\):
- \(G_{p}\) represents direction-independent effects.
- \(E_{ps}\) represents direction-dependent effects.
- \(L_{p}\) represents the feed rotation.
- \(K_{ps}\) represents the phase delay term.
- \(B_{s}\) represents the brightness matrix.
The RIME is more formally described in the following four papers:
- I. A full-sky Jones formalism
- II. Calibration and direction-dependent effects
- III. Addressing direction-dependent effects in 21cm WSRT observations of 3C147
- IV. A generalized tensor formalism
Numpy¶
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: |
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, coords, l_grid, m_grid, …) |
Computes Direction Dependent Effects (E) by sampling complex values in beam at the coordinates coords . |
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 . |
-
africanus.rime.
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} A_{ps} X_{pqs} A_{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 :
numpy.ndarray
Time index used to look up the antenna Jones index for a particular baseline. shape
(row,)
.- 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,)
.- dde1_jones :
numpy.ndarray
, optional \(A_{ps}\) Direction-Dependent Jones terms for the first antenna. shape
(source,time,ant,chan,corr_1,corr_2)
- source_coh :
numpy.ndarray
, optional \(X_{pqs}\) Direction-Dependent Coherency matrix for the baseline. with shape
(source,row,chan,corr_1,corr_2)
- dde2_jones :
numpy.ndarray
, optional \(A_{qs}\) Direction-Dependent Jones terms for the second antenna. shape
(source,time,ant,chan,corr_1,corr_2)
- die1_jones :
numpy.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 :
numpy.ndarray
, optional \(B_{pq}\) base visibilities, added to source coherency summation before multiplication with die1_jones and die2_jones.
- die2_jones :
numpy.ndarray
, optional \(G_{ps}\) Direction-Independent Jones terms for the second antenna of the baseline. with shape
(time,ant,chan,corr_1,corr_2)
Returns: - visibilities :
numpy.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
andant
(antenna) dimensions. - Each
row
is associated with a pair of antenna Jones matrices at a particular timestep via thetime_index
,antenna1
andantenna2
inputs. - The
row
dimension must be an increasing partial order in time.
-
africanus.rime.
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 :
numpy.ndarray
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,)
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 a positive sign convention and so any UVW coordinates must be inverted in order for their phase delay terms (and therefore visibilities) to agree.
- lm :
-
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 onpython-casacore
. This backend should be used by default.test
creates parallactic angles by multiplying thetimes
andantenna_position
arrays. It exist solely for testing.
Returns: - parallactic_angles :
numpy.ndarray
Parallactic angles of shape
(time,ant)
- times :
-
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)
- parallactic_angles :
-
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 theparallactic_angles
- Adding
pointing_errors
- Scaling by
antenna_scaling
Parameters: - lm :
numpy.ndarray
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.
- Rotating
-
africanus.rime.
beam_cube_dde
(beam, coords, l_grid, m_grid, freq_grid, spline_order=1, mode=u'nearest')[source]¶ Computes Direction Dependent Effects (E) by sampling complex values in
beam
at the coordinatescoords
.Both real and imaginary beam values are sampled at the given coordinates and normalised to form a mean of circular quantities.
l_grid
,m_grid
andfreq_grid
can be obtained frombeam_grids()
.Parameters: - beam :
numpy.ndarray
complex beam cube of shape
(beam_lw, beam_mh, beam_nud, corr_1, corr_2)
wherebeam_lw
is the grid width of the l dimension,beam_mh
is the grid height of the m dimension andbeam_nud
is the grid depth of the frequency dimension. Eithercorr_1
or bothcorr_1
andcorr_2
may be present, representing 1, 2 or 2x2 correlations respectively.- coords :
numpy.ndarray
beam cube coordinates of shape
(coords, dim_1, ..., dim_n)
wherecoord
always has size 3 and refers to (l,m,frequency).- l_grid :
numpy.ndarray
Monotonically increasing or decreasing grid values for the l axis, with shape
(beam_lw,)
. If decreasing, the- m_grid :
numpy.ndarray
Monotonically increasing or decreasing grid values for the m axis, with shape
(beam_mh,)
- freq_grid :
numpy.ndarray
Monotonically increasing grid values for the frequency axis, with shape
(beam_nud,)
- spline_order : int
Spline order to use in
scipy.ndimage.interpolation.map_coordinates()
. Defaults to 1 (‘linear’)- mode : str
Border mode to use in
scipy.ndimage.interpolation.map_coordinates()
Defaults to ‘nearest’
Returns: - ddes :
numpy.ndarray
Sampled complex beam values at the specified coordinates with shape
(dim_1, ..., dim_n, corr_1, corr_2)
- beam :
-
africanus.rime.
zernike_dde
(coords, coeffs, noll_index)[source]¶ Computes Direction Dependent Effects by evaluating Zernicke Polynomials defined by coefficients
coeffs
and noll indexesnoll_index
at the specified coordinatescoords
.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)
wherepoly
is the number of polynomial coefficients andcorr_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)
- coords :
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 . |
-
africanus.rime.cuda.
predict_vis
(time_index, antenna1, antenna2, dde1_jones, source_coh, dde2_jones, die1_jones, base_vis, die2_jones)[source]¶ Multiply Jones terms together to form model visibilities according to the following formula:
\[V_{pq} = G_{p} \left( B_{pq} + \sum_{s} A_{ps} X_{pqs} A_{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. shape
(row,)
.- 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 \(A_{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 \(A_{qs}\) Direction-Dependent Jones terms for the second antenna. 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 visibilities, added to source coherency summation before multiplication with die1_jones and die2_jones.
- die2_jones :
cupy.ndarray
, optional \(G_{ps}\) Direction-Independent Jones terms for the second antenna of the baseline. with 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
andant
(antenna) dimensions. - Each
row
is associated with a pair of antenna Jones matrices at a particular timestep via thetime_index
,antenna1
andantenna2
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,)
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 a positive sign convention and so any UVW coordinates must be inverted in order for their phase delay terms (and therefore visibilities) to agree.
- lm :
-
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)
- parallactic_angles :
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) |
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, coords, l_grid, m_grid, …) |
Computes Direction Dependent Effects (E) by sampling complex values in beam at the coordinates coords . |
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 . |
-
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)[source]¶ Multiply Jones terms together to form model visibilities according to the following formula:
\[V_{pq} = G_{p} \left( B_{pq} + \sum_{s} A_{ps} X_{pqs} A_{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. shape
(row,)
.- 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 \(A_{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 \(A_{qs}\) Direction-Dependent Jones terms for the second antenna. 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 visibilities, added to source coherency summation before multiplication with die1_jones and die2_jones.
- die2_jones :
dask.array.Array
, optional \(G_{ps}\) Direction-Independent Jones terms for the second antenna of the baseline. with shape
(time,ant,chan,corr_1,corr_2)
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
andant
(antenna) dimensions.Each
row
is associated with a pair of antenna Jones matrices at a particular timestep via thetime_index
,antenna1
andantenna2
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 eachrow
can contain any antenna, random access must be preserved along this dimension.The chunks in the
row
andtime
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]
indexing10
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
andtime
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:
The number chunks in
row
andtime
must match although the individual chunk sizes need not.Unique timesteps should not be split across row chunks.
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)
Use
aggregate_chunks()
to aggregate multiplerow
andtime
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)[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 :
dask.array.Array
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,)
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 a positive sign convention and so any UVW coordinates must be inverted in order for their phase delay terms (and therefore visibilities) to agree.
- lm :
-
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 onpython-casacore
. This backend should be used by default.test
creates parallactic angles by multiplying thetimes
andantenna_position
arrays. It exist solely for testing.
Returns: - parallactic_angles :
dask.array.Array
Parallactic angles of shape
(time,ant)
- times :
-
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)
- parallactic_angles :
-
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 theparallactic_angles
- Adding
pointing_errors
- Scaling by
antenna_scaling
Parameters: - lm :
dask.array.Array
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.
- Rotating
-
africanus.rime.dask.
beam_cube_dde
(beam, coords, l_grid, m_grid, freq_grid, spline_order=1, mode='nearest')[source]¶ Computes Direction Dependent Effects (E) by sampling complex values in
beam
at the coordinatescoords
.Both real and imaginary beam values are sampled at the given coordinates and normalised to form a mean of circular quantities.
l_grid
,m_grid
andfreq_grid
can be obtained frombeam_grids()
.Parameters: - beam :
dask.array.Array
complex beam cube of shape
(beam_lw, beam_mh, beam_nud, corr_1, corr_2)
wherebeam_lw
is the grid width of the l dimension,beam_mh
is the grid height of the m dimension andbeam_nud
is the grid depth of the frequency dimension. Eithercorr_1
or bothcorr_1
andcorr_2
may be present, representing 1, 2 or 2x2 correlations respectively.- coords :
dask.array.Array
beam cube coordinates of shape
(coords, dim_1, ..., dim_n)
wherecoord
always has size 3 and refers to (l,m,frequency).- l_grid :
dask.array.Array
Monotonically increasing or decreasing grid values for the l axis, with shape
(beam_lw,)
. If decreasing, the- m_grid :
dask.array.Array
Monotonically increasing or decreasing grid values for the m axis, with shape
(beam_mh,)
- freq_grid :
dask.array.Array
Monotonically increasing grid values for the frequency axis, with shape
(beam_nud,)
- spline_order : int
Spline order to use in
scipy.ndimage.interpolation.map_coordinates()
. Defaults to 1 (‘linear’)- mode : str
Border mode to use in
scipy.ndimage.interpolation.map_coordinates()
Defaults to ‘nearest’
Returns: - ddes :
dask.array.Array
Sampled complex beam values at the specified coordinates with shape
(dim_1, ..., dim_n, corr_1, corr_2)
- beam :
-
africanus.rime.dask.
zernike_dde
(coords, coeffs, noll_index)[source]¶ Computes Direction Dependent Effects by evaluating Zernicke Polynomials defined by coefficients
coeffs
and noll indexesnoll_index
at the specified coordinatescoords
.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)
wherepoly
is the number of polynomial coefficients andcorr_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)
- coords :
Direct Fourier Transform¶
Functions used to compute the discretised direct Fourier transform (DFT) for an ideal unpolarised interferometer. The DFT for an ideal interferometer is defined as
where \(u,v,w\) are data (visibility \(V\)) space coordinates and \(l,m,n\) are signal (image \(I\)) space coordinates. 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
where \(s\) labels the source (or pixel) location. This can be cast into a matrix equation as follows
where \(R\) is the operator that maps an
image to visibility space. This mapping is
implemented by the im_to_vis()
function.
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
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[, dtype]) |
Computes the discrete image to visibility mapping of an ideal unpolarised interferometer : |
vis_to_im (vis, uvw, lm, frequency[, dtype]) |
Computes visibility to image mapping of an ideal unpolarised interferometer: |
-
africanus.dft.
im_to_vis
(image, uvw, lm, frequency, dtype=None)[source]¶ Computes the discrete image to visibility mapping of an ideal unpolarised 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)
The Stokes I intensity in each pixel (flatten 2D array per channel).- uvw :
numpy.ndarray
UVW coordinates of shape
(row, 3)
with U, V and W components in the last dimension.- lm :
numpy.ndarray
LM coordinates of shape
(source, 2)
with L and M components in the last dimension.- frequency :
numpy.ndarray
frequencies of shape
(chan,)
- 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)
- image :
-
africanus.dft.
vis_to_im
(vis, uvw, lm, frequency, dtype=None)[source]¶ Computes visibility to image mapping of an ideal unpolarised 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)
The Stokes I visibilities of which to compute a dirty image- uvw :
numpy.ndarray
UVW coordinates of shape
(row, 3)
with U, V and W components in the last dimension.- lm :
numpy.ndarray
LM coordinates of shape
(source, 2)
with L and M components in the last dimension.- frequency :
numpy.ndarray
frequencies of shape
(chan,)
- 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)
- vis :
Dask¶
im_to_vis (image, uvw, lm, frequency[, dtype]) |
Computes the discrete image to visibility mapping of an ideal unpolarised interferometer : |
vis_to_im (vis, uvw, lm, frequency[, dtype]) |
Computes visibility to image mapping of an ideal unpolarised interferometer: |
-
africanus.dft.dask.
im_to_vis
(image, uvw, lm, frequency, dtype=<type 'numpy.complex128'>)[source]¶ Computes the discrete image to visibility mapping of an ideal unpolarised 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)
The Stokes I intensity in each pixel (flatten 2D array per channel).- uvw :
dask.array.Array
UVW coordinates of shape
(row, 3)
with U, V and W components in the last dimension.- lm :
dask.array.Array
LM coordinates of shape
(source, 2)
with L and M components in the last dimension.- frequency :
dask.array.Array
frequencies of shape
(chan,)
- 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)
- image :
-
africanus.dft.dask.
vis_to_im
(vis, uvw, lm, frequency, dtype=<type 'numpy.float64'>)[source]¶ Computes visibility to image mapping of an ideal unpolarised 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)
The Stokes I visibilities of which to compute a dirty image- uvw :
dask.array.Array
UVW coordinates of shape
(row, 3)
with U, V and W components in the last dimension.- lm :
dask.array.Array
LM coordinates of shape
(source, 2)
with L and M components in the last dimension.- frequency :
dask.array.Array
frequencies of shape
(chan,)
- 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)
- vis :
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 specifieduvw
coordinates andref_wave
reference wavelengths using the specifiedconvolution_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. 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 tonp.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, andnx
andny
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=<type 'numpy.complex64'>)[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. 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 specifieduvw
coordinates andref_wave
reference wavelengths using the specifiedconvolution_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. 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 toda.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, andnx
andny
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. 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
W Stacking¶
This is currently experimental
Implements W-Stacking as described in WSClean.
w_stacking_layers (w_min, w_max, l, m) |
Computes the number of w-layers given the minimum and maximum W coordinates, as well as the l and m coordinates. |
w_stacking_bins (w_min, w_max, w_layers) |
Returns the W coordinate bins appropriate for the observation parameters, given the minimum and maximum W coordinates and the number of W layers. |
w_stacking_centroids (w_bins) |
Returns the W coordinate centroids for each W layer. |
grid (vis, uvw, flags, weights, ref_wave, …) |
Convolutional W-stacking gridder. |
degrid (grids, uvw, weights, ref_wave, …[, …]) |
Convolutional W-stacking degridder (continuum) |
-
africanus.gridding.wstack.
w_stacking_layers
(w_min, w_max, l, m)[source]¶ Computes the number of w-layers given the minimum and maximum W coordinates, as well as the l and m coordinates.
\[N_{wlay} >> 2 \pi \left(w_{max} - w_{min} \right) \underset{l, m}{\max}\left(1 - \sqrt{1 - l^2 - m^2}\right)\]Parameters: - w_min : float
Minimum W coordinate in wavelengths.
- w_max : float
Maximum W coordinate in wavelengths.
- l :
numpy.ndarray
l coordinates
- m :
numpy.ndarray
m coordinates
Returns: - int
Number of w-layers
-
africanus.gridding.wstack.
w_stacking_bins
(w_min, w_max, w_layers)[source]¶ Returns the W coordinate bins appropriate for the observation parameters, given the minimum and maximum W coordinates and the number of W layers.
W coordinates can be binned by calling
w_bins = np.digitize(w, bins) - 1
Parameters: - w_min : float
Minimum W coordinate in wavelengths.
- w_max : float
Maximum W coordinate in wavelengths.
- w_layers : int
Number of w layers
Returns: - :class:`numpy.ndarray`
W-coordinate bins of shape
(nw + 1,)
.
Notes
A small epsilon is added to
w_max
to force this W coordinate into the last bin.
-
africanus.gridding.wstack.
w_stacking_centroids
(w_bins)[source]¶ Returns the W coordinate centroids for each W layer. Computed from bins produced by
w_stacking_bins()
.Parameters: - w_bins :
numpy.ndarray
W stacking bins of shape
(nw + 1,)
Returns: - :class:`numpy.ndarray`
W-coordinate centroids of shape
(nw,)
in wavelengths.
- w_bins :
-
africanus.gridding.wstack.
grid
(vis, uvw, flags, weights, ref_wave, convolution_filter, w_bins, cell_size, nx=1024, ny=1024, grids=None)[source]¶ Convolutional W-stacking gridder.
This function grids visibilities
vis
onto multiple grids, each associated with a W-layer defined byw_bins
. The W coordinate of theuvw
array is used to bin the visibility into the appropriate grid.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 :
numpy.ndarray
complex visibility array of shape
(row, chan, corr_1, corr_2)
- uvw :
numpy.ndarray
float64 array of UVW coordinates of shape
(row, 3)
- weights :
numpy.ndarray
float32 or float64 array of weights. 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 tonp.zeros_like(vis, dtype=np.bool)
as default.- ref_wave : np.ndarray
float64 array of wavelengths of shape
(chan,)
- convolution_filter :
ConvolutionFilter
Convolution filter
- w_bins :
numpy.ndarray
W coordinate bins of shape
(nw + 1,)
- 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
- grids : list of np.ndarray, optional
list of complex arrays of length
nw
, each with shape(ny, nx, corr_1, corr_2)
. If supplied, this array will be used as the gridding target, andnx
andny
will be derived from the grid’s dimensions.
Returns: - list of np.ndarray
list of complex arrays of gridded visibilities, of length
nw
, each with shape(ny, nx, corr_1, corr_2)
. The number of correlations may vary, depending on the shape of vis.
-
africanus.gridding.wstack.
degrid
(grids, uvw, weights, ref_wave, convolution_filter, w_bins, cell_size, dtype=<type 'numpy.complex64'>)[source]¶ Convolutional W-stacking 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: - grids : list of np.ndarray
list of visibility grids of length
nw
. of shape(ny, nx, corr_1, corr_2)
- uvw : np.ndarray
float64 array of UVW coordinates of shape
(row, 3)
- weights : np.ndarray
float32 or float64 array of weights. 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
- w_bins :
numpy.ndarray
W coordinate bins of shape
(nw + 1,)
- cell_size : float
Cell size in arcseconds.
- dtype :
numpy.dtype
, optional Numpy type of the resulting array. Defaults to
numpy.complex64
.
Returns: - np.ndarray
(row, chan, corr_1, corr_2)
complex ndarray of visibilities
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
andv
coordinates, as well as thewavelengths
, \(\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
andnx
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: - :class:`numpy.ndarray`
Cell size of
u
andv
in arcseconds with shape(2,)
Raises: - ValueError
If the cell size criteria are not matched.
- u :
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: - :class:`ConvolutionFilter`
namedtuple containing filter attributes
-
africanus.filters.
ConvolutionFilter
= <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: - :class:`numpy.ndarray`
Kaiser Bessel filter with the same shape as u
- 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: - :class:`numpy.ndarray`
Filter with the same shape as u
- 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: - x :
numpy.ndarray
Filter positions
- W : int
Width of the filter.
- beta : float
Kaiser bessel shape parameter
Returns: - :class:`numpy.ndarray`
Fourier Transform of the Kaiser Bessel, with the same shape as x.
- 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
Deconvolution Algorithms¶
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: - :class:`numpy.ndarray`
lm Direction Cosines of shape
(coord, 2)
- radec :
-
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: - :class:`numpy.ndarray`
lm Direction Cosines of shape
(coord, 3)
- radec :
-
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 :
numpy.ndarray
lm Direction Cosines of shape
(coord, 2)
- phase_centre :
numpy.ndarray
, optional radec coordinates of the Phase Centre. Shape
(2,)
Returns: - :class:`numpy.ndarray`
radec coordinates of shape
(coord, 2)
where Right-Ascension and Declination are in the last 2 components, respectively.
- lm :
-
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: - :class:`numpy.ndarray`
radec coordinates of shape
(coord, 2)
where Right-Ascension and Declination are in the last 2 components, respectively.
- lmn :
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: - :class:`dask.array.Array`
lm Direction Cosines of shape
(coord, 2)
- radec :
-
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: - :class:`dask.array.Array`
lm Direction Cosines of shape
(coord, 3)
- radec :
-
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 :
dask.array.Array
lm Direction Cosines of shape
(coord, 2)
- phase_centre :
dask.array.Array
, optional radec coordinates of the Phase Centre. Shape
(2,)
Returns: - :class:`dask.array.Array`
radec coordinates of shape
(coord, 2)
where Right-Ascension and Declination are in the last 2 components, respectively.
- lm :
-
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: - :class:`dask.array.Array`
radec coordinates of shape
(coord, 2)
where Right-Ascension and Declination are in the last 2 components, respectively.
- lmn :
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 linearXX,XY,YX,YY
and circularRR, 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
canoutput
can be arbitrarily nested or ordered lists, but the appropriate inputs must be present to produce the requested outputs.The elements of
input
andoutput
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 ofinput
. Must have the same shape as the last dimensions ofinput
.- 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 inoutput
.
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 }}
- input :
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 linearXX,XY,YX,YY
and circularRR, 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
canoutput
can be arbitrarily nested or ordered lists, but the appropriate inputs must be present to produce the requested outputs.The elements of
input
andoutput
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 ofinput
. Must have the same shape as the last dimensions ofinput
.- 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 inoutput
.
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 }}
- input :
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 linearXX,XY,YX,YY
and circularRR, 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
canoutput
can be arbitrarily nested or ordered lists, but the appropriate inputs must be present to produce the requested outputs.The elements of
input
andoutput
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 ofinput
. Must have the same shape as the last dimensions ofinput
.- 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 inoutput
.
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 }}
- input :
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 apol
dimension is present, then it must also be present onspi
.- 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)
.
- stokes :
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 apol
dimension is present, then it must also be present onspi
.- 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)
.
- stokes :
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
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=1e-06, maxiter=100, dtype=<type 'numpy.float64'>)[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]
- data :
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-06, maxiter=100, dtype=<type 'numpy.float64'>)[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]
- data :
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
See also
-
africanus.model.wsclean.
spectra
(I, coeffs, log_poly, 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 :
numpy.ndarray
flux density in Janskys at the reference frequency of shape
(source,)
- coeffs :
numpy.ndarray
Polynomial coefficients for each source of shape
(source, comp)
- log_poly :
numpy.ndarray
or bool boolean array of shape
(source, )
indicating whether logarithmic (True) or ordinary (False) polynomials should be used.- ref_freq :
numpy.ndarray
Source reference frequencies of shape
(source,)
- frequency :
numpy.ndarray
frequencies of shape
(chan,)
Returns: - spectral_model :
numpy.ndarray
Spectral Model of shape
(source, chan)
See also
- I :
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)
See also
- I :
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).
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:
- If the bin contains some unflagged data, only this data is used to calculate average.
- 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}}\]
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 |
CHAN_FREQ | Nominal | Mean | No |
CHAN_WIDTH | Nominal | Sum | 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 |
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, 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,)
.- 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 generally be
None
if the inputs wereNone
.
- time :
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, 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,)
.- 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 generally be
None
if the inputs wereNone
.
- time :
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 suppliedrequirements
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 aMissingPackageException
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 thanmax_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 requestedParameters: - 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,)
ifncorr == 1
(2,)
ifncorr == 2
(2,2)
ifncorr == 4
Beams¶
beam_filenames (filename_schema, …) |
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, polarisation_type)[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.
- polarisation_type : {‘linear’, ‘circular’}
String defining the type of polarisation.
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 byL
orX
CTYPEM
orY
CTYPEFREQ
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__
Contributing¶
Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.
You can contribute in many ways:
Types of Contributions¶
Report Bugs¶
Report bugs at https://github.com/ska-sa/codex-africanus/issues.
If you are reporting a bug, please include:
- Your operating system name and version.
- Any details about your local setup that might be helpful in troubleshooting.
- Detailed steps to reproduce the bug.
Fix Bugs¶
Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.
Implement Features¶
Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.
Write Documentation¶
Codex Africanus could always use more documentation, whether as part of the official Codex Africanus docs, in docstrings, or even on the web in blog posts, articles, and such.
Submit Feedback¶
The best way to send feedback is to file an issue at https://github.com/ska-sa/codex-africanus/issues.
If you are proposing a feature:
- Explain in detail how it would work.
- Keep the scope as narrow as possible, to make it easier to implement.
- Remember that this is a volunteer-driven project, and that contributions are welcome :)
Get Started!¶
Ready to contribute? Here’s how to set up codex-africanus for local development.
Fork the codex-africanus repo on GitHub.
Clone your fork locally:
$ git clone git@github.com:your_name_here/codex-africanus.git
Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development:
$ mkvirtualenv codex-africanus $ cd codex-africanus/ $ pip install -e .
Create a branch for local development:
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
When you’re done making changes, check that your changes pass the test cases, fixup your PEP8 compliance, and check for any code style issues:
$ py.test -v africanus $ autopep8 -r -i africanus $ flake8 africanus $ pycodestyle africanus
To get autopep8 and pycodestyle, just pip install them into your virtualenv.
Commit your changes and push your branch to GitHub:
$ git add . $ git commit -m "Your detailed description of your changes." $ git push origin name-of-your-bugfix-or-feature
Submit a pull request through the GitHub website.
Pull Request Guidelines¶
Before you submit a pull request, check that it meets these guidelines:
- The pull request should include tests.
- If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in HISTORY.rst.
- The pull request should work for Python 2.7, 3.5 and 3.6. Check https://travis-ci.org/ska-sa/codex-africanus/pull_requests and make sure that the tests pass for all supported Python versions.
Deploying¶
A reminder for the maintainers on how to deploy.
Start a release branch
$ git checkout -b prepare-release-Z.Y.X.
Update HISTORY.rst with the intended release number Z.Y.X and commit to git.
Bump the version number. If your current version is Z.Y.W and the new version is Z.Y.X call:
$ python -m pip install bumpversion $ bumpversion --current-version Z.Y.W --new-version Z.Y.X patch
Push the release branch to github and merge it.
$ git push origin prepare-release-Z.Y.X
Create the source and wheel distributions:
$ git checkout master $ git pull origin master $ python setup.py sdist bdist_wheel
Install twine and upload the source distribution to the pypi test server. Here, pypitest refers to to the pypi test server setup in a
.pypirc
file.:$ python -m pip install twine $ python -m twine upload -r pypitest dist/codex-africanus-Z.Y.X.tar.gz
Test pypi install on different python versions, running the test cases.
$ python -m virtualenv --python=pythonM.N test $ source test/bin/activate (test) $ pip install --index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple codex-africanus[complete]==Z.Y.X (test) $ py.test /path/to/tests
Upload the source distribution to the main pypi server. Here, pypi refers to to the main pypi setup in a
.pypirc
file.:$ python -m twine upload -r pypi dist/codex-africanus-Z.Y.X*
Tag the release commit, push the release commits and tag to github.:
$ git tag Z.Y.X $ git push $ git push --tags
Credits¶
Development Lead¶
- Simon Perkins <sperkins@ska.ac.za>
Contributors¶
- Landman Bester <lbester@ska.ac.za>
- Benjamin Hugo <bhugo@ska.ac.za>
- Gijs Molenaar <gijs@pythonic.nl>
- Joshua van Staden <joshvstaden14@gmail.com>
- Oleg Smirnov <oms@ska.ac.za, osmirnov@gmail.com>
History¶
0.1.6 (2019-05-09)¶
- Support automated travis releases.
0.1.5 (2019-05-09)¶
- Predict script enhancements (GH#103) and dask channel chunking fix (GH#104).
- Directly jit DFT functions (GH#100, GH#101)
- Spectral Models (GH#86)
- Fix radec sign conversion in wsclean sky model (GH#96)
- Full Time and Channel Averaging Implementation (GH#80, GH#97, GH#98)
- Support integer seconds in wsclean ra and dec columns (GH#91, GH#93)
- Fix ratio computation in Gaussian Shape (GH#89, GH#90)
0.1.4 (2019-03-11)¶
- Support complete and complete-cuda to support non-GPU installs (GH#87)
- Gaussian Shape Parameter Implementation (GH#82, GH#83)
- WSClean Spectral Model (GH#81)
- Compare predict versus MeqTrees (GH#79)
- Time and channel averaging (GH#75)
- cupy implementation of predict_vis (GH#73)
- Introduce transpose in second antenna term of predict (GH#72)
- cupy implementation of feed_rotation (GH#67)
- cupy implementation of stokes_convert kernel (GH#65)
- Add a basic RIME example (GH#64)
- requires_optional accepts ImportError’s for a better debugging experience (GH#62, GH#63)
- Added fit_component_spi function (GH#61)
- cupy implementation of the phase_delay kernel (GH#59)
- Correct phase_delay argument ordering (GH#57)
- Support dask for radec_to_lmn and lmn_to_radec. Also add support for radec_to_lm and lm_to_radec (GH#56)
- Added test for dft to test if image space covariance is symmetric(GH#55)
- Correct Parallactic Angle Computation (GH#49)
- Enhance visibility predict (GH#50)
- Fix Kaiser Bessel filter and taper (GH#48)
- Stokes/Correlation conversion (GH#41)
- Fix gridding examples (GH#43)
- Add simple dask gridder example (GH#42)
- Implement Kaiser Bessel filter (GH#38)
- Implement W-stacking gridder/degridder (GH#38)
- Use 2D filters by default (GH#37)
- Fixed bug in im_to_vis. Added more tests for im_to_vis. Removed division by \(n\) since it is trivial to reinstate after the fact. (GH#34)
- Move numba implementations out of API functions. (GH#33)
- Zernike Polynomial Direction Dependent Effects (GH#18, GH#30)
- Added division by \(n\) to DFT. Fixed dask chunking issue. Updated test_vis_to_im_dask (GH#29).
- Implement RIME visibility predict (GH#24, GH#25)
- Direct Fourier Transform (GH#19)
- Parallactic Angle computation (GH#15)
- Implement Feed Rotation term (GH#14)
- Swap gridding correlation dimensions (GH#13)
- Implement Direction Dependent Effect beam cubes (GH#12)
- Implement Brightness Matrix Calculation (GH#9)
- Implement RIME Phase Delay term (GH#8)
- Support user supplied grids (GH#7)
- Add dask wrappers to the gridder and degridder (GH#4)
- Add weights to gridder/degridder and remove PSF function (GH#2)
0.1.2 (2018-03-28)¶
- First release on PyPI.
\ Sort by:\ best rated\ newest\ oldest\
\\
Add a comment\ (markup):
\``code``
, \ code blocks:::
and an indented block after blank line