open

baseband.mark4.base.open(name, mode='rs', **kwargs)

Open Mark4 file(s) for reading or writing.

Opened as a binary file, one gets a wrapped filehandle that adds methods to read/write a frame. Opened as a stream, the handle is wrapped further, with methods such as reading and writing to the file as if it were a stream of samples.

Parameters:

namestr or filehandle, or sequence of str

File name, filehandle, sequence of file names, or template (file name(s) can be Path but template has to be str).

mode{‘rb’, ‘wb’, ‘rs’, or ‘ws’}, optional

Whether to open for reading or writing, and as a regular binary file or as a stream. Default: ‘rs’, for reading a stream.

**kwargs

Additional arguments when opening the file as a stream.

— For reading a stream(see Mark4StreamReader)

sample_rateQuantity, optional

Number of complete samples per second, i.e. the rate at which each channel is sampled. If not given, will be inferred from scanning two frames of the file.

ntrackint, optional

Number of Mark 4 bitstreams. If None (default), will attempt to automatically detect it by scanning the file.

decadeint or None

Decade of the observation start time (eg. 2010 for 2018), needed to remove ambiguity in the Mark 4 time stamp (default: None). Can instead pass an approximate ref_time.

ref_timeTime or None

Reference time within 4 years of the start time of the observations. Used only if decade is not given.

squeezebool, optional

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

subsetindexing object, optional

Specific channels of the complete sample to decode (after possible squeezing). If an empty tuple (default), all channels are read.

fill_valuefloat or complex, optional

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

verifybool or ‘fix’, optional

Whether to do basic checks of frame integrity when reading. Default: ‘fix’, which implies basic verification and replacement of gaps with zeros.

— For writing a stream(see Mark4StreamWriter)

header0Mark4Header

Header for the first frame, holding time information, etc. Can instead give keyword arguments to construct a header (see **kwargs).

sample_rateQuantity

Number of complete samples per second, i.e. the rate at which each channel is sampled. Needed to calculate header timestamps.

squeezebool, optional

If True (default), writer accepts squeezed arrays as input, and adds any dimensions of length unity.

file_sizeint or None, optional

When writing to a sequence of files, the maximum size of one file in bytes. If None (default), the file size is unlimited, and only the first file will be written to.

**kwargs

If no header is given, an attempt is made to construct one from these. For a standard header, this would include the following.

— Header keywords(see fromvalues())

timeTime

Start time of the file. Sets bcd-encoded unit year, day, hour, minute, second in the header.

ntrackint

Number of Mark 4 bitstreams (equal to number of channels times fanout times bps)

bpsint

Bits per elementary sample.

fanoutint

Number of tracks over which a given channel is spread out.

Returns:

Filehandle

Mark4FileReader or Mark4FileWriter (binary), or Mark4StreamReader or Mark4StreamWriter (stream)

Notes

Although it is not generally expected to be useful for Mark 4, like for other formats one can also pass to name a list, tuple, or subclass of FileNameSequencer. For writing to multiple files, the file_size keyword must be passed or only the first file will be written to. One may also pass in a sequentialfile object (opened in ‘rb’ mode for reading or ‘w+b’ for writing), though for typical use cases it is practically identical to passing in a list or template.