Sky Model

Functionality related to the Sky Model.

Coherency Conversion

Utilities for converting back and forth between stokes parameters and correlations

Numpy

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

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

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

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

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

Or circular correlations to stokes:

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

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

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

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

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

Parameters:
input : numpy.ndarray

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

input_schema : list of str or int

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

output_schema : list of str or int

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

Returns:
result : numpy.ndarray

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

Notes

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

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

Cuda

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

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

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

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

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

Or circular correlations to stokes:

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

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

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

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

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

Parameters:
input : cupy.ndarray

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

input_schema : list of str or int

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

output_schema : list of str or int

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

Returns:
result : cupy.ndarray

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

Notes

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

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

Dask

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

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

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

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

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

Or circular correlations to stokes:

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

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

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

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

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

Parameters:
input : dask.array.Array

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

input_schema : list of str or int

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

output_schema : list of str or int

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

Returns:
result : dask.array.Array

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

Notes

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

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

Spectral Model

Functionality for computing a Spectral Model.

Numpy

spectral_model(stokes, spi, ref_freq, frequency) Compute a spectral model, per polarisation.
africanus.model.spectral.spectral_model(stokes, spi, ref_freq, frequency, base=0)[source]

Compute a spectral model, per polarisation.

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

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

spi : numpy.ndarray

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

ref_freq : numpy.ndarray

Reference frequencies of shape (source,)

frequencies : numpy.ndarray

Frequencies of shape (chan,)

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

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

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

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

Returns:
spectral_model : numpy.ndarray

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

Dask

spectral_model(stokes, spi, ref_freq, …[, …]) Compute a spectral model, per polarisation.
africanus.model.spectral.dask.spectral_model(stokes, spi, ref_freq, frequencies, base=0)[source]

Compute a spectral model, per polarisation.

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

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

spi : dask.array.Array

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

ref_freq : dask.array.Array

Reference frequencies of shape (source,)

frequencies : dask.array.Array

Frequencies of shape (chan,)

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

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

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

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

Returns:
spectral_model : dask.array.Array

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

Spectral Index

Functionality related to the spectral index.

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

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

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

Numpy

fit_spi_components(data, weights, freqs, freq0) Computes the spectral indices and the intensity at the reference frequency of a spectral index model:
africanus.model.spi.fit_spi_components(data, weights, freqs, freq0, alphai=None, I0i=None, tol=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]

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]

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

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)

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)