Mark4Header

class baseband.mark4.header.Mark4Header(words, ntrack=None, decade=None, ref_time=None, verify=True)[source] [edit on github]

Bases: Mark4TrackHeader

Decoder/encoder of a Mark 4 Header, containing all streams.

See https://www.haystack.mit.edu/tech/vlbi/mark5/docs/230.3.pdf

Parameters:
wordsndarray of int, or None

Shape should be (5, number-of-tracks), and dtype np.uint32. If None, ntrack should be given and words will be initialized to 0.

ntrackNone or int

Number of Mark 4 bitstreams, to help initialize words if needed.

decadeint or None

Decade in which the observations were taken (needed to remove ambiguity in the Mark 4 time stamp). Can instead pass an approximate ref_time.

ref_timeTime or None

Reference time within 4 years of the observation time, used to infer the full Mark 4 timestamp. Used only if decade is not given.

verifybool, optional

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

Returns:
headerMark4Header

Attributes Summary

bps

Bits per elementary sample (either 1 or 2).

complex_data

Whether the data are complex.

converters

Converted ID and sideband used for each channel.

decade

Decade of year, to complement 'bcd_unit_year' from header.

fanout

Number of samples stored in one payload item of size ntrack.

fraction

Fractional seconds (decoded from 'bcd_fraction').

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 (ntrack * fanout) in the frame.

nsb

Number of side bands used.

ntrack

Number of Mark 4 bitstreams.

payload_nbytes

Size of the payload in bytes.

sample_shape

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

samples_per_frame

Number of complete samples in the frame.

stream_dtype

Stream dtype required to hold this header's number of tracks.

time

Convert BCD time code to Time object for all tracks.

track_assignment

Assignments of tracks to channels and fanout items.

track_id

Track identifier (decoded from 'bcd_track_id').

Methods Summary

copy(**kwargs)

Create a mutable and independent copy of the header.

fromfile(fh, ntrack[, decade, ref_time, verify])

Read Mark 4 header from file.

fromkeys(*args, **kwargs)

Initialise a header from parsed values.

fromvalues(ntrack[, decade, ref_time])

Initialise a header from parsed values.

get_time()

Convert BCD time code to Time object for all tracks.

infer_decade(ref_time)

Uses a reference time to set a header's decade.

invariant_pattern([invariants, ntrack])

Invariant pattern to help search for headers.

invariants()

Set of keys of invariant header parts.

keys()

All keys defined for this header.

set_time(time)

Convert Time object to BCD timestamp elements.

tofile(fh)

Write VLBI frame header to filehandle.

update([crc, verify])

Update the header by setting keywords or properties.

verify()

Verify header integrity.

Attributes Documentation

bps

Bits per elementary sample (either 1 or 2).

If set, combined with fanout and ntrack to update ‘magnitude_bit’ for all tracks.

complex_data

Whether the data are complex. Always False for Mark 4.

converters

Converted ID and sideband used for each channel.

Returns a structured array with numerical ‘converter’ and boolean ‘lsb’ entries (where True means lower sideband).

Can be set with a similar structured array or a dict; if just an an array is passed in, it will be assumed that the sideband has been set beforehand (e.g., by setting nsb) and that the array holds the converter IDs.

decade = None

Decade of year, to complement ‘bcd_unit_year’ from header.

fanout

Number of samples stored in one payload item of size ntrack.

If set, will update ‘fan_out’ for each track.

fraction

Fractional seconds (decoded from ‘bcd_fraction’).

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 (ntrack * fanout) in the frame.

If set, it is combined with ntrack and fanout to infer bps.

nsb

Number of side bands used.

If set, assumes all converters are upper sideband for 1, and that converter IDs alternate between upper and lower sideband for 2.

ntrack

Number of Mark 4 bitstreams.

payload_nbytes

Size of the payload in bytes.

Note that the payloads miss pieces overwritten by the header.

sample_shape

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

samples_per_frame

Number of complete samples in the frame.

If set, this uses the number of tracks to infer and set fanout.

stream_dtype

Stream dtype required to hold this header’s number of tracks.

time

Convert BCD time code to Time object for all tracks.

If all tracks have the same fractional seconds, only a single Time instance is returned.

Uses bcd-encoded ‘unit_year’, ‘day’, ‘hour’, ‘minute’, ‘second’ and ‘frac_sec’, plus decade from the initialisation to calculate the time. See https://www.haystack.mit.edu/tech/vlbi/mark5/docs/230.3.pdf

track_assignment

Assignments of tracks to channels and fanout items.

The assignments are inferred from tables 10-14 in https://www.haystack.mit.edu/tech/vlbi/mark5/docs/230.3.pdf except that 2 has been subtracted so that tracks start at 0, and that for 64 tracks the arrays are suitably enlarged by adding another set of channels.

The returned array has shape (fanout, nchan, bps).

track_id

Track identifier (decoded from ‘bcd_track_id’).

Methods Documentation

copy(**kwargs) [edit on github]

Create a mutable and independent copy of the header.

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

classmethod fromfile(fh, ntrack, decade=None, ref_time=None, verify=True)[source] [edit on github]

Read Mark 4 header from file.

Parameters:
fhfilehandle

To read header from.

ntrackint

Number of Mark 4 bitstreams.

decadeint or None

Decade in which the observations were taken. Can instead pass an approximate ref_time.

ref_timeTime or None

Reference time within 4 years of the observation time. Used only if decade is not given.

verifybool, optional

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

classmethod fromkeys(*args, **kwargs) [edit on github]

Initialise a header from parsed values.

Like fromvalues, but without any interpretation of keywords.

Raises:
KeyErrorif not all keys required are present in kwargs
classmethod fromvalues(ntrack, decade=None, ref_time=None, **kwargs)[source] [edit on github]

Initialise a header from parsed values.

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

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

Parameters:
ntrackint

Number of Mark 4 bitstreams.

decadeint or None, optional

Decade in which the observations were taken. Can instead pass an approximate ref_time. Not needed if time is given.

ref_timeTime or None, optional

Reference time within 4 years of the observation time. Used only if decade is not given, and not needed if time is given.

**kwargs

Values used to initialize header keys or methods.

— Header keywords(minimum for a complete header)
timeTime instance

Time of the first sample.

bpsint

Bits per elementary sample.

fanoutint

Number of tracks over which a given channel is spread out.

get_time()[source] [edit on github]

Convert BCD time code to Time object for all tracks.

If all tracks have the same fractional seconds, only a single Time instance is returned.

Uses bcd-encoded ‘unit_year’, ‘day’, ‘hour’, ‘minute’, ‘second’ and ‘frac_sec’, plus decade from the initialisation to calculate the time. See https://www.haystack.mit.edu/tech/vlbi/mark5/docs/230.3.pdf

infer_decade(ref_time)[source] [edit on github]

Uses a reference time to set a header’s decade.

Parameters:
ref_timeTime

Reference time within 5 years of the observation time.

classmethod invariant_pattern(invariants=None, ntrack=None)[source] [edit on github]

Invariant pattern to help search for headers.

On the class, like mark5access, we use use one bit more than the sync pattern in word 2, viz., lsb of word 1, which we assume is always 0 (it is the lowest bit of eight of ‘system_id’).

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

ntrackint, optional

Number of tracks. Required for getting class invariants, ignored for instances.

classmethod invariants() [edit on github]

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() [edit on github]

All keys defined for this header.

set_time(time)[source] [edit on github]

Convert Time object to BCD timestamp elements.

Parameters:
timeTime

The time to use for this header.

tofile(fh)[source] [edit on github]

Write VLBI frame header to filehandle.

update(crc=None, verify=True, **kwargs)[source] [edit on github]

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:
crcint or None, optional

If None (default), recalculate the CRC after updating.

verifybool, optional

If True (default), verify integrity after updating.

**kwargs

Arguments used to set keywords and properties.

verify()[source] [edit on github]

Verify header integrity.