VLBIFileReaderBase

class baseband.vlbi_base.base.VLBIFileReaderBase(fh_raw)

Bases: baseband.vlbi_base.base.VLBIFileBase

VLBI wrapped file reader base class.

Typically, a subclass will define read_header, read_frame, and find_header methods. This baseclass includes a get_frame_rate method which determines the frame rate by scanning the file for headers, looking for the maximum frame number that occurs before the jump down for the next second. This method requires the subclass to define a read_header method and assumes headers have a ‘frame_nr’ item, and define a payload_nbytes property (as do all standard VLBI formats).

Parameters

fh_rawfilehandle

Filehandle of the raw binary data file.

Attributes Summary

info()

Standardized information on file readers.

Methods Summary

close(self)
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_frames(self, pattern, \*[, mask, …])	Use a pattern to locate frame starts near the current position.
temporary_offset(self)	Context manager for temporarily seeking to another file position.

Attributes Documentation

info

Standardized information on 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.

Examples

The most common use is simply to print information:

>>> from baseband.data import SAMPLE_MARK5B
>>> from baseband import mark5b
>>> fh = mark5b.open(SAMPLE_MARK5B, 'rb')
>>> fh.info
File information:
format = mark5b
number_of_frames = 4
frame_rate = 6400.0 Hz
bps = 2
complex_data = False
readable = False

missing:  nchan: needed to determine sample shape, frame rate, ...
          kday, ref_time: needed to infer full times.

>>> fh.close()

>>> fh = mark5b.open(SAMPLE_MARK5B, 'rb', kday=56000, nchan=8)
>>> fh.info
File information:
format = mark5b
number_of_frames = 4
frame_rate = 6400.0 Hz
sample_rate = 32.0 MHz
samples_per_frame = 5000
sample_shape = (8,)
bps = 2
complex_data = False
start_time = 2014-06-13T05:30:01.000000000
readable = True

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

Attributes

formatstr or None

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

number_of_framesint

Number of frames in the file.

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.

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.

checksdict

Checks that were done to determine whether the file was readable (normally the only entry is ‘decodable’).

errorsdict

Any exceptions raised while trying to determine attributes or doing checks. Keyed by the attributes/checks.

warningsdict

Any warnings about the attributes or about the checks. Keyed by the attributes/checks.

Methods Documentation

close(self)

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 method cycles through headers, starting from the start of the file, finding the largest frame number before it jumps back to 0 for a new second.

Returns

frame_rateQuantity

Frames per second.

Raises

EOFError

If the file contains less than one second of data.

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

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

Note that the current position is always included.

Parameters

patternheader, ~numpy.ndaray, bytes, int, or iterable of int

Synchronization pattern to look for. If a header or header class, invariant_pattern() is used to create a masked pattern, using invariant keys from invariants(). If an ndarray or bytes instance, a byte array view is taken. If an (iterable of) int, the integers need to be unsigned 32 bit and will be interpreted as little-endian.

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.

frame_nbytesint, optional

Frame size in bytes. Defaults to the frame size in any header passed in.

offsetint, optional

Offset from the frame start that the pattern occurs. Any offsets inferred from masked entries are added to this (hence, no offset needed when a header is passed in as pattern).

forwardbool, optional

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

maximumint, optional

Maximum number of bytes to search away from the present location. Default: search twice the frame size if given, otherwise 1 million (extra bytes to avoid partial patterns will be added). 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). Ignored if frame_nbytes is not given. 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 not corrupted.

Returns

locationslist of int

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

temporary_offset(self)

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.