katsdpmodels package

Submodules

katsdpmodels.band_mask module

Masks for roll-off at the edges of a band.

class katsdpmodels.band_mask.BandMask

Bases: katsdpmodels.models.SimpleHDF5Model

classmethod from_hdf5(hdf5: h5py._hl.files.File) → katsdpmodels.band_mask.BandMask

Load a model from an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

is_masked(spectral_window: katsdpmodels.band_mask.SpectralWindow, frequency: astropy.units.quantity.Quantity, channel_width: astropy.units.quantity.Quantity = <Quantity 0. Hz>) → Any
model_type: ClassVar[typing_extensions.Literal[‘band_mask’]] = 'band_mask'
to_hdf5(hdf5: h5py._hl.files.File) → None

Write a model to an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

class katsdpmodels.band_mask.BandMaskRanges(ranges: astropy.table.table.Table)

Bases: katsdpmodels.band_mask.BandMask

classmethod from_hdf5(hdf5: h5py._hl.files.File) → _B

Load a model from an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

is_masked(spectral_window: katsdpmodels.band_mask.SpectralWindow, frequency: astropy.units.quantity.Quantity, channel_width: astropy.units.quantity.Quantity = <Quantity 0. Hz>) → Any
model_format: ClassVar[typing_extensions.Literal[‘ranges’]] = 'ranges'
to_hdf5(hdf5: h5py._hl.files.File) → None

Write a model to an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

class katsdpmodels.band_mask.SpectralWindow(bandwidth: astropy.units.quantity.Quantity, centre_frequency: astropy.units.quantity.Quantity)

Bases: object

Defines a frequency range for use with BandMask.

property max_frequency
property min_frequency

katsdpmodels.models module

Base functionality common to all model types.

exception katsdpmodels.models.AbsoluteAliasError(*args)

Bases: katsdpmodels.models.ModelError

An alias retried to redirect to an absolute URL.

exception katsdpmodels.models.ChecksumError(*args)

Bases: katsdpmodels.models.DataError

The model did not match the checksum embedded in the filename.

exception katsdpmodels.models.DataError(*args)

Bases: katsdpmodels.models.ModelError

The model was missing some data or it had the wrong format.

exception katsdpmodels.models.FileTypeError(*args)

Bases: katsdpmodels.models.ModelError

The file type (as determined by Content-Type or extension) was not recognised.

class katsdpmodels.models.Model

Bases: abc.ABC

Base class for models.

Models can either be loaded from file-like objects or constructed directly. Models loaded by the fetcher store the checksum of the raw data, and are considered equal if the checksums match. Otherwise, equality is by object identity.

Models loaded by the fetcher should not be modified, as they may be shared by other users. Instead, make a copy and modify that.

Subclassing should generally be done in two layers:

  1. A class that defines model_type and defines the interface for that model type. This will be passed to fetchers to indicate what model type is expected. Due to limitations in mypy, this should not use @abstractmethod for the interface methods.

  2. A concrete implementation that defines model_format.

author: Optional[str] = None
checksum: Optional[str] = None
close() → None

Close external resources associated with the model.

Attempting to use the model after that results in undefined behavior. However, it is legal to call close() multiple times.

Models also implement the context manager protocol.

comment: Optional[str] = None
created: Optional[datetime.datetime] = None
abstract classmethod from_file(file: Union[io.IOBase, BinaryIO], url: str, *, content_type: Optional[str] = None) → _M

Load a model from raw data.

On success, the callee takes responsibility for closing file, either within the function itself or the close() method of the returned model.

If content_type is given, it should be used to determine the file type; otherwise url may be used instead.

model_format: ClassVar[str]
model_type: ClassVar[str]
target: Optional[str] = None
abstract to_file(file: Union[str, pathlib.Path, io.IOBase, BinaryIO], *, content_type: Optional[str] = None) → None

Write a model to file, overwriting any existing file.

If content_type is given, it should be used to determine the file type; otherwise the filename may be used.

version: Optional[int] = None
exception katsdpmodels.models.ModelError(*args)

Bases: ValueError

A model was found, but the content was incorrect.

classmethod with_urls(*args, url: Optional[str] = None, original_url: Optional[str] = None) → _E
exception katsdpmodels.models.ModelFormatError(*args)

Bases: katsdpmodels.models.ModelError

The model_format attribute was missing or did not match a known value.

exception katsdpmodels.models.ModelTypeError(*args)

Bases: katsdpmodels.models.ModelError

The model_type attribute was missing or did not match the expected value.

exception katsdpmodels.models.ModelVersionError(*args)

Bases: katsdpmodels.models.ModelError

The model_version attribute was missing or of the wrong type.

class katsdpmodels.models.SimpleHDF5Model

Bases: katsdpmodels.models.Model

Helper base class for models that load data from HDF5.

It does not handle lazy loading: the from_hdf5() class method must load all the data out of the HDF5 file as it will be closed by the caller. The implementation of from_hdf5() does not need to pull out the generic metadata (comment, target, author etc).

classmethod from_file(file: Union[io.IOBase, BinaryIO], url: str, *, content_type: Optional[str] = None) → _H

Load a model from raw data.

On success, the callee takes responsibility for closing file, either within the function itself or the close() method of the returned model.

If content_type is given, it should be used to determine the file type; otherwise url may be used instead.

abstract classmethod from_hdf5(hdf5: h5py._hl.files.File) → _H

Load a model from an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

model_format: ClassVar[str]
model_type: ClassVar[str]
to_file(file: Union[str, pathlib.Path, io.IOBase, BinaryIO], *, content_type: Optional[str] = None) → None

Write a model to file, overwriting any existing file.

If content_type is given, it should be used to determine the file type; otherwise the filename may be used.

abstract to_hdf5(hdf5: h5py._hl.files.File) → None

Write a model to an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

exception katsdpmodels.models.TelescopeStateError(*args)

Bases: katsdpmodels.models.ModelError

There was a problem retrieving references from telescope state.

exception katsdpmodels.models.TooManyAliasesError(*args)

Bases: katsdpmodels.models.ModelError

The limit on the number of alias redirections was reached.

katsdpmodels.models.get_hdf5_attr(attrs: Mapping[str, object], name: str, required_type: Type[_T], *, required: typing_extensions.Literal[True]) → _T
katsdpmodels.models.get_hdf5_attr(attrs: Mapping[str, object], name: str, required_type: Type[_T], *, required: bool = 'False') → Optional[_T]

Retrieve an attribute from an HDF5 object and verify its type.

Pass the attrs attribute of the HDF5 file, group or dataset as the attrs parameter. If the name is not present, returns None, unless required=True is passed.

The implementation includes a workaround for https://github.com/h5py/h5py/issues/379, which will decode byte attributes to Unicode. It also turns numpy scalars into plain Python types.

Raises
katsdpmodels.models.get_hdf5_dataset(group: h5py._hl.group.Group, name: str) → h5py._hl.dataset.Dataset

Get a dataset from an HDF5 file, raising an exception if missing.

The advantage of this method over directly indexing the group is that it will also raise the exception if a group is found instead of a dataset.

katsdpmodels.models.require_columns(name: str, array: Any, dtype: Any, ndim: int) → Any

Validate the columns in a table and the dimensionality.

The dtype is the expected dtype, which may be a structured dtype. The array is checked for compatibility: it must have all the required fields (but may have more), and they must be castable to the the expected dtype. Alternatively, if dtype is non-structured, the array must have a dtype that can be cast. In both cases, ‘same_kind’ casting is required.

The return value is the input array restricted to the required columns and cast to the required dtype. It may be either a view or a copy, depending on whether any casting was required.

This function is not designed to support nested structuring, and will not recursively filter out unwanted sub-structures.

Raises

DataError – if the types are not compatible or the wrong number of dimensions are present.

katsdpmodels.models.rfc3339_to_datetime(timestamp: str) → datetime.datetime

Convert a string in RFC 3339 format to a timezone-aware datetime object.

The original timezone in the string is lost, and the returned datetime is based on UTC.

katsdpmodels.primary_beam module

Primary beam models.

class katsdpmodels.primary_beam.AltAzFrame

Bases: astropy.utils.misc.ShapedLikeNDArray

Coordinate system aligned with the antenna.

The l coordinate is horizontal and increases with increasing azimuth (north to east), while the m coordinate is vertical and increases with increasing altitude. Both are defined by an orthographic (SIN) projection, with the nominal pointing centre at zero.

property shape

The shape of the underlying data.

class katsdpmodels.primary_beam.OutputType(value)

Bases: enum.Enum

An enumeration.

JONES_HV = 1

Jones matrix with linear basis corresponding to horizontal and vertical directions. See PrimaryBeam for sign conventions.

JONES_XY = 2

Jones matrix with linear basis corresponding to the IAU X (north) and Y (east) directions on the celestial sphere.

MUELLER = 3

A 4x4 Mueller matrix describing the effect on each Stokes parameter (IQUV), assuming that both antennas share the same beam and parallactic angle.

UNPOLARIZED_POWER = 4

Scalar power attenuation of unpolarized sources, assuming that both antennas share the same beam and parallactic angle. This is the same as the first element of MUELLER.

class katsdpmodels.primary_beam.PrimaryBeam

Bases: katsdpmodels.models.SimpleHDF5Model

Base class for primary beams.

The phase of the electric field at a point increases with time i.e., the phasor is

\[e^{(\omega t - kz)i}\]

The “ideal” complex voltage is multiplied by the beam model to obtain the measured voltage.

If you stick your right arm out and left hand up, then pretend to be an antenna (lean back and look at the sky) then they correspond to the directions of positive horizontal and vertical polarization respectively (the absolute signs don’t matter but the signs relative to each other do for cross-hand terms).

An instance of this class describes either a single antenna or an average of multiple antennas; to do antenna-specific modelling you will need a separate instance of this class per antenna.

This provides a normalized primary beam, describing the effect on off-axis pointing relative to the pointing centre. Thus, at the pointing centre it is the identity Jones matrix. If the primary beam Jones matrix in a given direction (returned from this model) is \(E\) and the direction-independent effects such as receiver gain and leakage are \(G\), then the combined effect is \(GE\).

property antenna

The antenna to which this model applies.

If this model is not antenna-specific or does not carry this information, it will be None.

property band

String identifier of the receiver band to which this model applies.

circumradius(frequency: astropy.units.quantity.Quantity) → float

Maximum distance from the pointing centre at which model has any coverage.

property frequency_range

Minimum and maximum frequency covered by the model.

property frequency_resolution

Approximate frequency resolution of the model.

Sampling at significantly higher spectral resolution than this will have diminishing returns compared to sampling at this resolution and interpolating.

classmethod from_hdf5(hdf5: h5py._hl.files.File) → katsdpmodels.primary_beam.PrimaryBeam

Load a model from an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

inradius(frequency: astropy.units.quantity.Quantity) → float

Maximum distance from the pointing centre at which model has full coverage.

property is_circular

Whether this model is circularly-symmetric about the pointing centre.

property is_unpolarized

Whether this model ignores polarization.

If true, it is guaranteed that the Jones matrices describing the beam are scaled identity matrices.

model_type: ClassVar[typing_extensions.Literal[‘primary_beam’]] = 'primary_beam'
property receiver

The receiver ID to which this model applies.

If this model is not specific to a single receiver or the model does not carry this information, it will be None.

sample(l: Any, m: Any, frequency: astropy.units.quantity.Quantity, frame: Union[katsdpmodels.primary_beam.AltAzFrame, katsdpmodels.primary_beam.RADecFrame], output_type: katsdpmodels.primary_beam.OutputType, *, out: Optional[numpy.ndarray] = None) → numpy.ndarray

Sample the primary beam.

A sample is returned for each combination of a position (given by l, m) with a frequency. The dimensions of the output will be (in order):

  • those of frequency

  • those of l, m and frame (which are broadcast with each other)

  • the row and column for matrices if output_type is one of the matrix types.

Parameters

  • l – Horizontal coordinates (interpreted according to frame).

  • m – Vertical coordinates (interpreted according to frame).

  • frequency – Frequencies to sample

  • frame – Specifies how to interpret the coordinates.

  • output_type – The value to compute. See OutputType for details.

  • out – If specified, provides the memory into which the result will be written. It must have the correct shape, the dtype must be complex64 (or float32 for OutputType.UNPOLARIZED_POWER) and it must be C contiguous.

Raises
sample_grid(l: Any, m: Any, frequency: astropy.units.quantity.Quantity, frame: Union[katsdpmodels.primary_beam.AltAzFrame, katsdpmodels.primary_beam.RADecFrame], output_type: katsdpmodels.primary_beam.OutputType, *, out: Optional[numpy.ndarray] = None) → numpy.ndarray

Sample the primary beam on a grid aligned to the axes.

This is equivalent to sample(l[np.newaxis, :], m[:, np.newaxis], ...), but may be significantly faster (depending on the implementation), and is not guaranteed to give bit-identical results. This advantage may be lost when using RADecFrame with a non-zero parallactic angle.

The grid need not be regularly spaced, but an output is generated for each combination of l, m and frequency.

Refer to sample() for further details of the parameters and return value.

spatial_resolution(frequency: astropy.units.quantity.Quantity) → numpy.ndarray

Approximate spatial resolution of the model, in units of projected coordinates.

Sampling a grid at significantly higher resolution than this will have diminishing returns compared to sampling at this resolution and interpolating.

to_hdf5(hdf5: h5py._hl.files.File) → None

Write a model to an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

class katsdpmodels.primary_beam.PrimaryBeamAperturePlane(x_start: astropy.units.quantity.Quantity, y_start: astropy.units.quantity.Quantity, x_step: astropy.units.quantity.Quantity, y_step: astropy.units.quantity.Quantity, frequency: astropy.units.quantity.Quantity, samples: numpy.ndarray, *, band: str, antenna: Optional[str] = None, receiver: Optional[str] = None)

Bases: katsdpmodels.primary_beam.PrimaryBeam

Primary beam model represented in the aperture plane.

This is a Fourier transform of the primary beam response. See Model file formats for details.

property antenna

The antenna to which this model applies.

If this model is not antenna-specific or does not carry this information, it will be None.

property band

String identifier of the receiver band to which this model applies.

circumradius(frequency: astropy.units.quantity.Quantity) → float

Maximum distance from the pointing centre at which model has any coverage.

frequency_range() → Tuple[astropy.units.quantity.Quantity, astropy.units.quantity.Quantity]

Minimum and maximum frequency covered by the model.

frequency_resolution() → astropy.units.quantity.Quantity

Approximate frequency resolution of the model.

Sampling at significantly higher spectral resolution than this will have diminishing returns compared to sampling at this resolution and interpolating.

classmethod from_hdf5(hdf5: h5py._hl.files.File) → _P

Load a model from an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

classmethod from_katholog(model, *, antenna: Optional[str] = None, band: Optional[str] = None) → _P

Load a model represented in the katholog package.

Parameters

  • model (katholog.Aperture) – The katholog model from which to load.

  • antenna – The antenna name for which to load data. If no value is specified, the array average is loaded.

  • band – The name of the band to set in the returned model. If no value is provided, will try to determine it from the katholog model.

Raises

ValueError – If model does not indicate a band and band was not provided.

inradius(frequency: astropy.units.quantity.Quantity) → float

Maximum distance from the pointing centre at which model has full coverage.

property is_circular

Whether this model is circularly-symmetric about the pointing centre.

property is_unpolarized

Whether this model ignores polarization.

If true, it is guaranteed that the Jones matrices describing the beam are scaled identity matrices.

model_format: ClassVar[typing_extensions.Literal[‘aperture_plane’]] = 'aperture_plane'
property receiver

The receiver ID to which this model applies.

If this model is not specific to a single receiver or the model does not carry this information, it will be None.

sample(l: Any, m: Any, frequency: astropy.units.quantity.Quantity, frame: Union[katsdpmodels.primary_beam.AltAzFrame, katsdpmodels.primary_beam.RADecFrame], output_type: katsdpmodels.primary_beam.OutputType, *, out: Optional[numpy.ndarray] = None) → numpy.ndarray

Sample the primary beam.

A sample is returned for each combination of a position (given by l, m) with a frequency. The dimensions of the output will be (in order):

  • those of frequency

  • those of l, m and frame (which are broadcast with each other)

  • the row and column for matrices if output_type is one of the matrix types.

Parameters

  • l – Horizontal coordinates (interpreted according to frame).

  • m – Vertical coordinates (interpreted according to frame).

  • frequency – Frequencies to sample

  • frame – Specifies how to interpret the coordinates.

  • output_type – The value to compute. See OutputType for details.

  • out – If specified, provides the memory into which the result will be written. It must have the correct shape, the dtype must be complex64 (or float32 for OutputType.UNPOLARIZED_POWER) and it must be C contiguous.

Raises
sample_grid(l: Any, m: Any, frequency: astropy.units.quantity.Quantity, frame: Union[katsdpmodels.primary_beam.AltAzFrame, katsdpmodels.primary_beam.RADecFrame], output_type: katsdpmodels.primary_beam.OutputType, *, out: Optional[numpy.ndarray] = None) → numpy.ndarray

Sample the primary beam on a grid aligned to the axes.

This is equivalent to sample(l[np.newaxis, :], m[:, np.newaxis], ...), but may be significantly faster (depending on the implementation), and is not guaranteed to give bit-identical results. This advantage may be lost when using RADecFrame with a non-zero parallactic angle.

The grid need not be regularly spaced, but an output is generated for each combination of l, m and frequency.

Refer to sample() for further details of the parameters and return value.

spatial_resolution(frequency: astropy.units.quantity.Quantity) → numpy.ndarray

Approximate spatial resolution of the model, in units of projected coordinates.

Sampling a grid at significantly higher resolution than this will have diminishing returns compared to sampling at this resolution and interpolating.

to_hdf5(hdf5: h5py._hl.files.File) → None

Write a model to an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

property x

x coordinates associated with the samples.

property y

y coordinates associated with the samples.

class katsdpmodels.primary_beam.RADecFrame(parallactic_angle: astropy.units.quantity.Quantity)

Bases: astropy.utils.misc.ShapedLikeNDArray

Coordinate system aligned with a celestial sphere.

The l coordinate is aligned with right ascension and the m coordinate with declination, and increase in the corresponding directions. Both are defined by an orthographic (SIN) projection, with the nominal pointing centre at zero.

Any RA/Dec system can be used (e.g. ICRS/GCRS/CIRS) as long as the parallactic angle is computed for the same system.

This currently only models parallactic angle rotation. Relativistic aberration can cause a small scaling of offsets between barycentric and topocentric frames, but it’s ignored as it is typically much smaller than features of the primary beam.

This class should not be constructed directly, as the constructor signature is subject to change in future. Use the factory methods such as from_parallactic_angle() and from_sky_coord().

Parameters

parallactic_angle – Rotation angle to align the celestial sphere with the antenna. See katpoint.Target.parallactic_angle() for a definition.

classmethod from_parallactic_angle(parallactic_angle: astropy.units.quantity.Quantity) → katsdpmodels.primary_beam.RADecFrame

Generate a frame from a parallactic angle.

classmethod from_sky_coord(target: astropy.coordinates.sky_coordinate.SkyCoord) → katsdpmodels.primary_beam.RADecFrame

Generate a frame from a target (assuming an AltAz mount).

The target must have obstime and location properties, and must be scalar. It will be converted to ICRS if necessary.

jones_hv_to_xy() → numpy.ndarray

Jones matrix that converts voltages from HV to XY.

See OutputType for further clarification.

lm_to_hv() → numpy.ndarray

Matrix that converts (ra, dec) offsets to (h, v) offsets.

property shape

The shape of the underlying data.

katsdpmodels.rfi_mask module

Masks for radio-frequency interference.

class katsdpmodels.rfi_mask.RFIMask

Bases: katsdpmodels.models.SimpleHDF5Model

classmethod from_hdf5(hdf5: h5py._hl.files.File) → katsdpmodels.rfi_mask.RFIMask

Load a model from an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

is_masked(frequency: astropy.units.quantity.Quantity, baseline_length: astropy.units.quantity.Quantity, channel_width: astropy.units.quantity.Quantity = <Quantity 0. Hz>) → Any

Determine whether given frequency is masked for given baseline length.

The return value is either a boolean (if frequency, baseline_length and channel_width are scalar) or an array of boolean if they’re arrays, with the usual broadcasting rules applying.

A channel is masked if any part of the channel overlaps with RFI. The channel has width channel_width and is centred on frequency. This also honours the mask_auto_correlations property for baseline lengths of zero.

property mask_auto_correlations

Return whether auto-correlations should be masked too.

Auto-correlations are defined as baselines with zero length, which includes cross-hand polarisation products. This property indicates whether auto-correlations should be masked, in which case it is done for frequencies covered by any of the ranges. That is, if this is False, no auto-correlations will be masked for RFI. If this is True, auto-correlations are treated like any other baselines.

max_baseline_length(frequency: astropy.units.quantity.Quantity, channel_width: astropy.units.quantity.Quantity = <Quantity 0. Hz>) → Any

Maximum baseline length for which data at frequency should be masked.

If the frequency is not masked at all, returns a negative length, and if it is masked at all baseline lengths, returns +inf. One may also supply an array of frequencies and receive an array of responses. This does not include the effect of the mask_auto_correlations property when returning a value of zero.

model_type: ClassVar[typing_extensions.Literal[‘rfi_mask’]] = 'rfi_mask'
to_hdf5(hdf5: h5py._hl.files.File) → None

Write a model to an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

class katsdpmodels.rfi_mask.RFIMaskRanges(ranges: astropy.table.table.Table, mask_auto_correlations: bool)

Bases: katsdpmodels.rfi_mask.RFIMask

classmethod from_hdf5(hdf5: h5py._hl.files.File) → _R

Load a model from an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

is_masked(frequency: astropy.units.quantity.Quantity, baseline_length: astropy.units.quantity.Quantity, channel_width: astropy.units.quantity.Quantity = <Quantity 0. Hz>) → Any

Determine whether given frequency is masked for given baseline length.

The return value is either a boolean (if frequency, baseline_length and channel_width are scalar) or an array of boolean if they’re arrays, with the usual broadcasting rules applying.

A channel is masked if any part of the channel overlaps with RFI. The channel has width channel_width and is centred on frequency. This also honours the mask_auto_correlations property for baseline lengths of zero.

property mask_auto_correlations

Return whether auto-correlations should be masked too.

Auto-correlations are defined as baselines with zero length, which includes cross-hand polarisation products. This property indicates whether auto-correlations should be masked, in which case it is done for frequencies covered by any of the ranges. That is, if this is False, no auto-correlations will be masked for RFI. If this is True, auto-correlations are treated like any other baselines.

max_baseline_length(frequency: astropy.units.quantity.Quantity, channel_width: astropy.units.quantity.Quantity = <Quantity 0. Hz>) → Any

Maximum baseline length for which data at frequency should be masked.

If the frequency is not masked at all, returns a negative length, and if it is masked at all baseline lengths, returns +inf. One may also supply an array of frequencies and receive an array of responses. This does not include the effect of the mask_auto_correlations property when returning a value of zero.

model_format: ClassVar[typing_extensions.Literal[‘ranges’]] = 'ranges'
to_hdf5(hdf5: h5py._hl.files.File) → None

Write a model to an HDF5 file.

Subclasses will implement this method, but it is not intended to be used directly.

Module contents