open

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

Open GUPPI 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 GUPPIStreamReader)

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 possibly squeezing). If a single indexing object is passed, it selects polarizations. With a tuple, the first selects polarizations and the second selects channels. If the tuple is empty (default), all components are read.

— For writing a stream(see GUPPIStreamWriter)

header0GUPPIHeader

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

squeezebool, optional

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

frames_per_fileint, optional

When writing to a sequence of files, sets the number of frames within each file. Default: 128.

**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. Must have an integer number of seconds.

sample_rateQuantity

Number of complete samples per second, i.e. the rate at which each channel of each polarization is sampled.

samples_per_frameint

Number of complete samples per frame. Can alternatively give payload_nbytes.

payload_nbytesint

Number of bytes per payload. Can alternatively give samples_per_frame.

offsetQuantity or TimeDelta, optional

Time offset from the start of the whole observation (default: 0).

npolint, optional

Number of polarizations (default: 1).

nchanint, optional

Number of channels (default: 1). For GUPPI, complex data is only allowed when nchan > 1.

bpsint, optional

Bits per elementary sample, i.e. per real or imaginary component for complex data (default: 8).

Returns:

Filehandle

GUPPIFileReader or GUPPIFileWriter (binary), or GUPPIStreamReader or GUPPIStreamWriter (stream).

Notes

For streams, one can also pass to name a list of files, or a template string that can be formatted using ‘stt_imjd’, ‘src_name’, and other header keywords (by GUPPIFileNameSequencer).

For writing, one can mimic, for example, what is done at Arecibo by using the template ‘puppi_{stt_imjd}_{src_name}_{scannum}.{file_nr:04d}.raw’. GUPPI typically has 128 frames per file; to change this, use the frames_per_file keyword. file_size is set by frames_per_file and cannot be passed.

For reading, to read series such as the above, you will need to use something like ‘puppi_58132_J1810+1744_2176.{file_nr:04d}.raw’. Here we have to pass in the MJD, source name and scan number explicitly, since the template is used to get the first file name, before any header is read, and therefore the only keyword available is ‘file_nr’, which is assumed to be zero for the first file. To avoid this restriction, pass in keyword arguments with values appropriate for the first file.

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.