GUPPIFileReader

class baseband.guppi.base.GUPPIFileReader(fh_raw)

Bases: baseband.vlbi_base.base.VLBIFileReaderBase

Simple reader for GUPPI files.

Wraps a binary filehandle, providing methods to help interpret the data, such as read_frame and get_frame_rate. By default, frame payloads are mapped rather than fully read into physical memory.

Parameters

fh_rawfilehandle

Filehandle of the raw binary data file.

Attributes Summary

info()

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.
read_frame(self[, memmap, verify])	Read the frame header and read or map the corresponding payload.
read_header(self)	Read a single header from the file.
temporary_offset(self)	Context manager for temporarily seeking to another file position.

Attributes Documentation

info

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 routine uses the sample rate and number of samples per frame (excluding overlap) from the first header in the file.

Returns

frame_rateQuantity

Frames per second.

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.

read_frame(self, memmap=True, verify=True)

Read the frame header and read or map the corresponding payload.

Parameters

memmapbool, optional

If True (default), map the payload using memmap, so that parts are only loaded into memory as needed to access data.

verifybool, optional

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

Returns

frameGUPPIFrame

With .header and .payload properties. The .data property returns all data encoded in the frame. Since this may be too large to fit in memory, it may be better to access the parts of interest by slicing the frame.

read_header(self)

Read a single header from the file.

Returns

headerGUPPIHeader

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.