StreamReaderBase

class baseband.base.base.StreamReaderBase(fh_raw, header0, *, squeeze=True, subset=(), fill_value=0.0, verify=True, **kwargs)

Bases: StreamBase

Base for all stream readers, providing standard reading methods.

Parameters:

fh_rawfilehandle

Should be opened in binary mode for reading, and usually wrapped in a given format;s FileReader.

header0header instance

First header of the file, with information like the start time, etc.

squeezebool, optional

If True (default), remove any dimensions of length unity from decoded data.

subsetindexing object or tuple of objects, optional

Specific components of the complete sample to decode (after possible squeezing).

fill_valuefloat or complex, optional

Value to use for invalid or missing data. Default: 0.

verifybool, optional

Whether to do basic checks of frame integrity when reading. The first frameset of the stream is always checked. Default: True.

**kwargs

Information that supplements that of the header. In particular, any format should define bps, complex_data, samples_per_frame, and sample_shape (pre-squeeze and subset). Furthermore, sample_rate should be provided if the raw file reader cannot determine it.

Notes

Accessing frames happens via a number of private methods, which can be overridden by subclasses to deal with their peculiarities.

The process starts in read with _get_frame(offset), which determines the index of the frame a given offset falls in, and then either uses _read_frame(index) to read it or returns a possibly cached frame, together with the sample_offset at which offset falls within the frame. Then, data is retrieved as needed until the frame is exhausted, at which point the process repeats.

The _read_frame(index) method in turn takes a number of steps. First, the binary file reader is moved to the correct position using _seek_frame(index), then for the base reader, the actual reading is done using _fh_raw_read_frame() and a check is made that the right frame was read.

Various formats override various steps. For instance, DADA overrides _fh_raw_read_frame() to take care of last frames, which are often longer than the fixed lengths recorded in the header. For GUPPI, _get_frame is overridden to take into account overlap between frames, which should not be skipped for the last frame. For GSB, _seek_frame and _fh_raw_read_frame are both overridden to take into account that header and data are read from different files.

Attributes Summary

bps	Bits per elementary sample.
complex_data	Whether the data are complex.
dtype
fill_value	Value to use for invalid or missing data.
header0	First header of the file.
info	Standardized information on stream readers.
ndim	Number of dimensions of the (squeezed/subset) stream data.
sample_rate	Number of complete samples per second.
sample_shape	Shape of a complete sample (possibly subset or squeezed).
samples_per_frame	Number of complete samples per frame.
shape	Shape of the (squeezed/subset) stream data.
size	Total number of component samples in the (squeezed/subset) stream data.
squeeze	Whether data arrays have dimensions with length unity removed.
start_time	Start time of the file.
stop_time	Time at the end of the file, just after the last sample.
subset	Specific components of the complete sample to decode.
time	Time of the sample pointer's current offset in file.
verify	Whether to do consistency checks on frames being read.

Methods Summary

close()
read([count, out])	Read a number of complete samples.
readable()	Whether the file can be read and decoded.
seek(offset[, whence])	Change the sample pointer position.
tell([unit])	Current offset in the file.

Attributes Documentation

bps

Bits per elementary sample.

complex_data

Whether the data are complex.

dtype

fill_value

Value to use for invalid or missing data. Default: 0.

header0

First header of the file.

info

Standardized information on stream readers.

The info descriptor provides a few standard attributes, most of which can also be accessed directly on the stream filehandle, and tests basic readability of the stream. More detailed information on the underlying file is stored in its info, accessible via info.file_info (and shown by __repr__).

ndim

Number of dimensions of the (squeezed/subset) stream data.

sample_rate

sample_shape

Shape of a complete sample (possibly subset or squeezed).

samples_per_frame

Number of complete samples per frame.

shape

Shape of the (squeezed/subset) stream data.

size

Total number of component samples in the (squeezed/subset) stream data.

squeeze

Whether data arrays have dimensions with length unity removed.

If True, data read out has such dimensions removed, and data passed in for writing has them inserted.

start_time

Start time of the file.

See also time for the time of the sample pointer’s current offset, and (if available) stop_time for the time at the end of the file.

stop_time

Time at the end of the file, just after the last sample.

See also start_time for the start time of the file, and time for the time of the sample pointer’s current offset.

subset

Specific components of the complete sample to decode.

The order of dimensions is the same as for sample_shape. Set by the class initializer.

time

Time of the sample pointer’s current offset in file.

See also start_time for the start time, and (if available) stop_time for the end time, of the file.

verify

Whether to do consistency checks on frames being read.

Methods Documentation

close()

read(count=None, out=None)

Read a number of complete samples.

Parameters:

countint or None, optional

Number of complete samples to read. If None (default) or negative, the number of samples left. Ignored if out is given.

outNone or array, optional

Array to store the samples in. If given, count will be inferred from the first dimension; the remaining dimensions should equal sample_shape.

Returns:

outndarray of float or complex

The first dimension is sample-time, and the remaining ones are as given by sample_shape.

readable()

Whether the file can be read and decoded.

seek(offset, whence=0)

Change the sample pointer position.

This works like a normal filehandle seek, but the offset is in samples (or a relative or absolute time).

Parameters:

offsetint, Quantity, or Time

Offset to move to. Can be an (integer) number of samples, an offset in time units, or an absolute time. For the latter two, the pointer will be moved to the nearest integer sample.

whence{0, 1, 2, ‘start’, ‘current’, or ‘end’}, optional

Like regular seek, the offset is taken to be from the start if whence=0 (default), from the current position if 1, and from the end if 2. One can alternativey use ‘start’, ‘current’, or ‘end’ for 0, 1, or 2, respectively. Ignored if offset is a time.

tell(unit=None)

Current offset in the file.

Parameters:

unitUnit or str, optional

Time unit the offset should be returned in. By default, no unit is used, i.e., an integer enumerating samples is returned. For the special string ‘time’, the absolute time is calculated.

Returns:

offsetint, Quantity, or Time

Offset in current file (or time at current position).