Mark4FileReader

class baseband.mark4.base.Mark4FileReader(fh_raw, ntrack=None, decade=None, ref_time=None)

Bases: baseband.vlbi_base.base.VLBIFileReaderBase

Simple reader for Mark 4 files.

Wraps a binary filehandle, providing methods to help interpret the data, such as locate_frame, read_frame and get_frame_rate.

Parameters

fh_rawfilehandle

Filehandle of the raw binary data file.

ntrackint or None, optional.

Number of Mark 4 bitstreams. Can be determined automatically as part of locating the first frame.

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.

Attributes Summary

fh_raw
info()	Standardized information on Mark 4 file readers.

Methods Summary

close(self)
determine_ntrack(self[, maximum])	Determines the number of tracks, by seeking the next frame.
find_header(self, *args, **kwargs)	Find the nearest header from the current position.
get_frame_rate(self)	Determine the number of frames per second.
locate_frame(self, *args, **kwargs)	Deprecated since version 3.1.
locate_frames(self[, pattern, mask, …])	Use a pattern to locate frame starts near the current position.
read_frame(self[, verify])	Read a single frame (header plus payload).
read_header(self)	Read a single header from the file.
temporary_offset(self[, offset, whence])	Context manager for temporarily seeking to another file position.

Attributes Documentation

fh_raw = None

info

Standardized information on Mark 4 file readers.

The info descriptor has a number of standard attributes, which are determined from arguments passed in opening the file, from the first header (info.header0) and from possibly scanning the file to determine the duration of frames. This class has two additional attributes specific to Mark 4 files (ntrack and offset0, see below).

Examples

The most common use is simply to print information:

>>> from baseband.data import SAMPLE_MARK4
>>> from baseband import mark4
>>> fh = mark4.open(SAMPLE_MARK4, 'rb')
>>> fh.info
File information:
format = mark4
number_of_frames = 2
frame_rate = 400.0 Hz
sample_rate = 32.0 MHz
samples_per_frame = 80000
sample_shape = (8,)
bps = 2
complex_data = False
readable = True
ntrack = 64
offset0 = 2696

missing:  decade, ref_time: needed to infer full times.

checks:  decodable: True
>>> fh.close()

>>> fh = mark4.open(SAMPLE_MARK4, 'rb', decade=2010)
>>> fh.info
File information:
format = mark4
number_of_frames = 2
frame_rate = 400.0 Hz
sample_rate = 32.0 MHz
samples_per_frame = 80000
sample_shape = (8,)
bps = 2
complex_data = False
start_time = 2014-06-16T07:38:12.475000000
readable = True
ntrack = 64
offset0 = 2696

checks:  decodable: True
>>> fh.close()

Attributes

formatstr or None

File format, or None if the underlying file cannot be parsed.

frame_rateQuantity

Number of data frames per unit of time.

sample_rateQuantity

Complete samples per unit of time.

samples_per_frameint

Number of complete samples in each frame.

sample_shapetuple

Dimensions of each complete sample (e.g., (nchan,)).

bpsint

Number of bits used to encode each elementary sample.

complex_databool

Whether the data are complex.

start_timeTime

Time of the first complete sample.

ntrackint

Number of “tape tracks” simulated in the disk file.

offset0int

Offset in bytes from the start of the file to the location of the first header.

readablebool

Whether the first sample could be read and decoded.

missingdict

Entries are keyed by names of arguments that should be passed to the file reader to obtain full information. The associated entries explain why these arguments are needed. For Mark 4, the possible entries are decade and ref_time.

errorsdict

Any exceptions raised while trying to determine attributes. Keyed by the attributes.

Methods Documentation

close(self)

determine_ntrack(self, maximum=None)

Determines the number of tracks, by seeking the next frame.

Uses locate_frame to look for the first occurrence of a frame from the current position for all supported ntrack values. Returns the first ntrack for which locate_frame is successful, setting the file’s ntrack property appropriately, and leaving the file pointer at the start of the frame.

Parameters

maximumint, optional

Maximum number of bytes forward to search through. Default: twice the frame size (20000 * ntrack // 8).

Returns

ntrackint or None

Number of Mark 4 bitstreams.

Raises

~baseband.vlbi_base.base.HeaderNotFoundError

If no frame was found for any value of ntrack.

find_header(self, *args, **kwargs)

Find the nearest header from the current position.

If successful, the file pointer is left at the start of the header.

Parameters are as for locate_frames.

Returns

header

Retrieved header.

Raises

~baseband.vlbi_base.base.HeaderNotFoundError

If no header could be located.

AssertionError

If the header did not pass verification.

get_frame_rate(self)

Determine the number of frames per second.

The frame rate is calculated from the time elapsed between the first two frames, as inferred from their time stamps.

Returns

frame_rateQuantity

Frames per second.

locate_frame(self, *args, **kwargs)

Deprecated since version 3.1: The locate_frame function is deprecated and may be removed in a future version. Use locate_frames or find_header instead.

Use a pattern to locate the frame nearest the current position.

Like locate_frames, but selects the closest frame and leaves the file pointer at its position.

Returns

locationint

The location of the file pointer.

Raises

~baseband.vlbi_base.base.HeaderNotFoundError

If no frame was found.

locate_frames(self, pattern=None, *, mask=None, frame_nbytes=None, offset=0, forward=True, maximum=None, check=1)

Use a pattern to locate frame starts near the current position.

Parameters

patternheader, ~numpy.ndaray, bytes, or (iterable of) int, optional

Synchronization pattern to look for. The default uses the Mark 4 sync pattern, plus that the bit before is 0. See invariant_pattern.

mask~numpy.ndarray, bytes, int, or iterable of int.

Bit mask for the pattern, with 1 indicating a given bit will be used the comparison. Only used if pattern is given and is not a header.

frame_nbytesint, optional

Frame size in bytes. Defaults to the frame size for ntrack. If given, overrides self.ntrack.

offsetint, optional

Offset from the frame start that the pattern occurs. Only used if pattern is given and not a header.

forwardbool, optional

Seek forward if True (default), backward if False.

maximumint, optional

Maximum number of bytes to search away from the present location. Use 0 to check only at the current position.

checkint or tuple of int, optional

Frame offsets where another sync pattern should be present (if inside the file). Default: 1, i.e., a sync pattern should be present one frame after the one found (independent of forward), thus helping to guarantee the frame is OK.

Returns

locationslist of int

Locations of sync patterns within the range scanned, in order of proximity to the starting position.

read_frame(self, verify=True)

Read a single frame (header plus payload).

Returns

frameMark4Frame

With .header and .data properties that return the Mark4Header and data encoded in the frame, respectively.

verifybool, optional

Whether to do basic checks of frame integrity. Default: True.

read_header(self)

Read a single header from the file.

Returns

headerMark4Header

temporary_offset(self, offset=None, whence=0)

Context manager for temporarily seeking to another file position.

To be used as part of a with statement:

with fh_raw.temporary_offset() [as fh_raw]:
    with-block

On exiting the with-block, the file pointer is moved back to its original position. As a convenience, one can pass on the offset to seek to when entering the context manager. Parameters are as for io.IOBase.seek().