VDIFFileReader

class baseband.vdif.base.VDIFFileReader(fh_raw)[source] [edit on github]

Bases: VLBIFileReaderBase

Simple reader for VDIF files.

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

Parameters:
fh_rawfilehandle

Filehandle of the raw binary data file.

Attributes Summary

fh_raw

info

Methods Summary

close()

find_header([pattern, edv, mask, ...])

Find the nearest header from the current position.

get_frame_rate()

Determine the number of frames per second.

get_thread_ids([check])

Determine the number of threads in the VDIF file.

locate_frames(pattern, *[, mask, ...])

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

read_frame([edv, verify])

Read a single frame (header plus payload).

read_frameset([thread_ids, edv, verify])

Read a single frame (header plus payload).

read_header([edv, verify])

Read a single header from the file.

temporary_offset([offset, whence])

Context manager for temporarily seeking to another file position.

Attributes Documentation

fh_raw = None
info

Methods Documentation

close() [edit on github]
find_header(pattern=None, *, edv=None, mask=None, frame_nbytes=None, offset=0, forward=True, maximum=None, check=1)[source] [edit on github]

Find the nearest header from the current position.

Search for a valid header at a given position which is consistent with pattern and/or with a header a frame size ahead. Note that the search is much slower if no pattern is given, as at every position it is tried to read a header, and then check for another one one frame ahead. It helps to pass in edv and frame_nbytes (if known).

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

Parameters:
patternVDIFHeader, array of byte, or compatible

If given, used for a direct search.

edvint

EDV of the header, used if pattern is not given.

maskarray of byte, bytes, iterable of int, string or int

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

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, nor is an offset needed for a full search).

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 10000 (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 header should be present. 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:
headerVDIFHeader

Retrieved VDIF header.

Raises:
~baseband.base.base.HeaderNotFoundError

If no header could be located.

AssertionError

If the header did not pass verification.

get_frame_rate()[source] [edit on github]

Determine the number of frames per second.

This method first tries to determine the frame rate by looking for the highest frame number in the first second of data. If that fails, it attempts to extract the sample rate from the header.

Returns:
frame_rateQuantity

Frames per second.

get_thread_ids(check=2)[source] [edit on github]

Determine the number of threads in the VDIF file.

The file is presumed to be positioned at the start of a header. Usually, it suffices to just seek to the start of the file, but if not, use find_header.

Parameters:
checkint, optional

Number of extra frames to check. Frame sets are scanned until the number of thread IDs found no longer increases for check frames.

Returns:
thread_idslist

Sorted list of all thread ids encountered in the frames scanned.

locate_frames(pattern, *, mask=None, frame_nbytes=None, offset=0, forward=True, maximum=None, check=1) [edit on github]

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(edv=None, verify=True)[source] [edit on github]

Read a single frame (header plus payload).

Parameters:
edvint, optional

The expected extended data version for the VDIF Header. If None, use that of the first frame. (Passing it in slightly improves file integrity checking.)

verifybool, optional

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

Returns:
frameVDIFFrame

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

read_frameset(thread_ids=None, edv=None, verify=True)[source] [edit on github]

Read a single frame (header plus payload).

Parameters:
thread_idslist, optional

The thread ids that should be read. If None (default), read all threads.

edvint, optional

The expected extended data version for the VDIF Header. If None, use that of the first frame. (Passing it in slightly improves file integrity checking.)

verifybool, optional

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

Returns:
framesetVDIFFrameSet

With .headers and .data properties that return a list of VDIFHeader and the data encoded in the frame set, respectively.

read_header(edv=None, verify=True)[source] [edit on github]

Read a single header from the file.

Parameters:
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.

Returns:
headerVDIFHeader
temporary_offset(offset=None, whence=0) [edit on github]

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