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: numpy.dtype, ndim: int) → Any

Validate the columns in a table and the dimensionality.

The dtype is the expected dtype, which must 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.

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.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