VDIFHeader

class baseband.vdif.header.VDIFHeader(words=None, edv=None, verify=True, **kwargs)

Bases: VLBIHeaderBase

VDIF Header, supporting different Extended Data Versions.

Will initialize a header instance appropriate for a given EDV. See https://vlbi.org/wp-content/uploads/2019/03/VDIF_specification_Release_1.1.1.pdf

Parameters:

wordstuple of int, or None

Eight (or four for legacy VDIF) 32-bit unsigned int header words. If None, set to a tuple of zeros for later initialisation.

edvint, False, or None, optional

Extended data version. If False, a legacy header is used. If None (default), it is determined from the header words; hence, setting it explicitly is useful mostly for a slight speed-up. (Subclasses can override this default with an _edv attribute.)

verifybool

Whether to do basic verification of integrity. Default: True.

Returns:

headerVDIFHeader subclass

As appropriate for the extended data version.

Attributes Summary

bps	Bits per elementary sample.
complex_data	Whether the data are complex.
edv	VDIF Extended Data Version (EDV).
frame_nbytes	Size of the frame in bytes.
mutable	Whether the header can be modified.
nbytes	Size of the header in bytes.
nchan	Number of channels in the frame.
payload_nbytes	Size of the payload in bytes.
ref_time	Reference time for the header, as encoded by 'ref_epoch'.
sample_shape	Shape of a sample in the payload (nchan,).
samples_per_frame	Number of complete samples in the frame.
station	Station ID: two ASCII characters, or 16-bit int.
time	Converts ref_epoch, seconds, and frame_nr to Time object.

Methods Summary

copy()	Create a mutable and independent copy of the header.
from_mark5b_header(mark5b_header, bps, ...)	Construct an Mark5B over VDIF header (EDV=0xab).
fromfile(fh[, edv, verify])	Read VDIF Header from file.
fromkeys(**kwargs)	Initialise a header from parsed values.
fromvalues([edv, verify])	Initialise a header from parsed values.
get_time([frame_rate])	Converts ref_epoch, seconds, and frame_nr to Time object.
invariant_pattern([invariants])	Pattern and mask shared between headers of a type or stream.
invariants()	Set of keys of invariant header parts.
keys()	All keys defined for this header.
same_stream(other)	Whether header is consistent with being from the same stream.
set_time(time[, frame_rate])	Converts Time object to ref_epoch, seconds, and frame_nr.
tofile(fh)	Write VLBI frame header to filehandle.
update(*[, verify])	Update the header by setting keywords or properties.
verify()	Verify that the length of the words is consistent.

Attributes Documentation

bps

Bits per elementary sample.

complex_data

Whether the data are complex.

edv

VDIF Extended Data Version (EDV).

frame_nbytes

Size of the frame in bytes.

mutable

Whether the header can be modified.

nbytes

Size of the header in bytes.

nchan

Number of channels in the frame.

payload_nbytes

Size of the payload in bytes.

ref_time

Reference time for the header, as encoded by ‘ref_epoch’.

If set, will use the nearest reference epoch before the given time.

sample_shape

Shape of a sample in the payload (nchan,).

samples_per_frame

Number of complete samples in the frame.

station

Station ID: two ASCII characters, or 16-bit int.

time

Converts ref_epoch, seconds, and frame_nr to Time object.

Uses ‘ref_epoch’, which stores the number of half-years from 2000, and ‘seconds’. By default, it also calculates the offset using the current frame number. For non-zero ‘frame_nr’, this requires the frame rate, which is calculated from the sample rate in the header.

Parameters:

frame_rateQuantity, optional

For non-zero ‘frame_nr’, this is required to calculate the corresponding offset.

Returns:

timeTime

Methods Documentation

copy()

Create a mutable and independent copy of the header.

Keyword arguments can be passed on as needed by possible subclasses.

classmethod from_mark5b_header(mark5b_header, bps, nchan, **kwargs)

Construct an Mark5B over VDIF header (EDV=0xab).

See https://vlbi.org/wp-content/uploads/2019/03/vdif_extension_0xab.pdf

Note that the Mark 5B header does not encode the bits-per-sample and the number of channels used in the payload, so these need to be given separately. A complete frame can be encapsulated with from_mark5b_frame.

Parameters:

mark5b_headerMark5BHeader

Used to set time, etc.

bpsint

Bits per elementary sample.

nchanint

Number of channels carried in the Mark 5B payload.

**kwargs

Any further arguments. Strictly, none are necessary to create a valid VDIF header, but this can be used to pass on, e.g., invalid_data.

classmethod fromfile(fh, edv=None, verify=True)

Read VDIF Header from file.

Parameters:

fhfilehandle

To read data from.

edvint, False, or None, optional

Extended data version. If False, a legacy header is used. If None (default), it is determined from the header. (Given it explicitly is mostly useful for a slight speed-up.)

verifybool, optional

Whether to do basic verification of integrity. Default: True.

classmethod fromkeys(**kwargs)

Initialise a header from parsed values.

Like fromvalues(), but without any interpretation of keywords.

Raises:

KeyErrorif not all keys required are pass in.

classmethod fromvalues(edv=False, *, verify=True, **kwargs)

Initialise a header from parsed values.

Here, the parsed values must be given as keyword arguments, i.e., for any header = cls(<data>), cls.fromvalues(**header) == header.

However, unlike for the fromkeys() class method, data can also be set using arguments named after methods, such as bps and time.

Given defaults:

invalid_data : False legacy_mode : False vdif_version : 1 thread_id : 0 frame_nr : 0 sync_pattern : 0xACABFEED for EDV 1 and 3, 0xa5ea5 for EDV 2

Values set by other keyword arguments (if present):

bits_per_sample : from bps frame_length : from samples_per_frame or frame_nbytes lg2_nchan : from nchan station_id : from station sampling_rate, sampling_unit : from sample_rate ref_epoch, seconds, frame_nr : from time

Note that to set time to non-integer seconds one also needs to pass in frame_rate or sample_rate.

get_time(frame_rate=None)

Converts ref_epoch, seconds, and frame_nr to Time object.

Uses ‘ref_epoch’, which stores the number of half-years from 2000, and ‘seconds’. By default, it also calculates the offset using the current frame number. For non-zero ‘frame_nr’, this requires the frame rate, which is calculated from the sample rate in the header.

Parameters:

frame_rateQuantity, optional

For non-zero ‘frame_nr’, this is required to calculate the corresponding offset.

Returns:

timeTime

classmethod invariant_pattern(invariants=None, **kwargs)

Pattern and mask shared between headers of a type or stream.

This is mostly for use inside locate_frames().

Parameters:

invariantsset of str, optional

Set of keys to header parts that are shared between all headers of a given type or within a given stream/file. Default: from invariants().

**kwargs

Keyword arguments needed to instantiate an empty header. (Mostly for Mark 4).

Returns:

patternlist of int

The pattern that is shared between headers. If called on an instance, just the header words; if called on a class, words with defaults for the relevant parts set.

masklist of int

For each entry in pattern a bit mask with bits set for the parts that are invariant.

classmethod invariants()

Set of keys of invariant header parts.

On the class, this returns keys of parts that are shared by all headers for the type, on an instance, those that are shared with other headers in the same file.

If neither are defined, returns ‘sync_pattern’ if the header containts that key.

keys()

All keys defined for this header.

same_stream(other)

Whether header is consistent with being from the same stream.

set_time(time, frame_rate=None)

Converts Time object to ref_epoch, seconds, and frame_nr.

For non-integer seconds, a frame rate is needed to calculate the ‘frame_nr’.

Parameters:

timeTime

The time to use for this header.

frame_rateQuantity, optional

For calculating ‘frame_nr’ from the fractional seconds.

tofile(fh)

Write VLBI frame header to filehandle.

update(*, verify=True, **kwargs)

Update the header by setting keywords or properties.

Here, any keywords matching header keys are applied first, and any remaining ones are used to set header properties, in the order set by the class (in _properties).

Parameters:

verifybool, optional

If True (default), verify integrity after updating.

**kwargs

Arguments used to set keywords and properties.

verify()

Verify that the length of the words is consistent.

Subclasses should override this to do more thorough checks.