Data Readers

TBW

Python module to reading in data from both 12-bit and 4-bit TBW files. This module defines the following classes for storing the TBW data found in a file:

Frame

object that contains all data associated with a particular TBW frame. The primary consituents of each frame are:

  • FrameHeader - the TBW frame header object and
  • FrameData - the TBW frame data object.

Combined, these two objects contain all of the information found in the original TBW frame.

The functions defined in this module fall into two class:
  1. convert a frame in a file to a Frame object and
  2. describe the format of the data in the file.

For reading in data, use the readFrame function. It takes a python file- handle as an input and returns a fully-filled Frame object. readFrame is designed to work with both 4-bit and 12-bit observations.

For describing the format of data in the file, two function are provided:

getDataBits
read in the first frame of an open file handle and return whether or not the data is 12 or 4-bit
getFramesPerObs

read in the first several frames to see how many stands are found in the data. .. note:

This function is a little flaky on TBW data sets that have less 
than a full complement or 12M (36M) samples.
class lsl.reader.tbw.FrameHeader(frameCount=None, secondsCount=None, tbwID=None, raw=None)

Class that stores the information found in the header of a TBW frame. All three fields listed in the DP IDC version H are stored as well as the original binary header data.

getDataBits()
Function to parse the TBW ID field and return the size of number of bits that comprise the data. 12 is returned for 12-bit data, and 4 for 4-bit data.
isTBW()
Function to check if the data is really TBW and not TBN by examining the TBW ID field. Returns True if the data is TBW, false otherwise.
parseID()
Function to parse the TBW ID field and return the stand number.
class lsl.reader.tbw.FrameData(timeTag=None, samples=400, xy=None)

Class that stores the information found in the data section of a TBW frame. Both fields listed in the DP IDC version H are stored.

getTime()
Function to convert the time tag from samples since station midnight to seconds since station midnight. This function needs to dp_common module in order to work.
class lsl.reader.tbw.Frame(header=<lsl.reader.tbw.FrameHeader object at 0x2bc6a10>, data=<lsl.reader.tbw.FrameData object at 0x2bc6a90>)

Class that stores the information contained within a single TBW frame. It’s properties are FrameHeader and FrameData objects.

getDataBits()
Convenience wrapper for the Frame.FrameHeader.getDataBits function.
getTime()
Convenience wrapper for the Frame.FrameData.getTime function.
parseID()
Convenience wrapper for the Frame.FrameHeader.parseID function.
lsl.reader.tbw.readFrame(filehandle, Verbose=False)
Function to read in a single TBW frame (header+data) and store the contents as a Frame object. This function wraps readerHeader and readData[(12)|4].
lsl.reader.tbw.getDataBits(filehandle)
Find out the number of data bits used in the file be reading in the first frame.
lsl.reader.tbw.getFramesPerObs(filehandle)
Find out how many frames are present per observation by examining the first frames for what would be 256 stands. This is done by reading two frames and then skipping the next 30,000.

TBN

Python module for reading data in from TBN files.This module defines the following classes for storing the TBN data found in a file:

Frame

object that contains all data associated with a particular TBN frame. The primary constituents of each frame are:

  • FrameHeader - the TBN frame header object and
  • FrameData - the TBN frame data object.

Combined, these two objects contain all of the information found in the original TBN frame.

ObservingBlock
object that stores a collection of Frames for all stands/polarizations for a particular time.

In addition to storing the data available in the frame, the Frame object also has attributes for holding information about the gain, central frequency, and filter code used for the observations.

The functions defined in this module fall into two class:
  1. convert a frame in a file to a Frame object and
  2. describe the format of the data in the file.

For reading in data, use the readFrame function. It takes a python file- handle as an input and returns a fully-filled Frame object. The readBlock function reads in a (user-defined) number of TBN frames and returns a ObservingBlock object.

For describing the format of data in the file, two function are provided:

getSampleRate
read in the few frame of an open file handle and return the sampling rate of the data
getFramesPerObs
read in the first several frames to see how many stands are found in the data.
class lsl.reader.tbn.FrameHeader(frameCount=None, secondsCount=None, tbnID=None, raw=None)

Class that stores the information found in the header of a TBW frame. All three fields listed in the DP IDC version H are stored as well as the original binary header data.

isTBN()
Function to check if the data is really TBN and not TBW by examining the TBN ID field. Returns True if the data is TBN, false otherwise.
parseID()
Function to parse the TBN ID field and return a tuple of the stand number and polarization.
class lsl.reader.tbn.FrameData(timeTag=None, iq=None)

Class that stores the information found in the data section of a TBN frame. Both fields listed in the DP IDC version H are stored.

getFilterCode()
Function to convert the sample rate in Hz to a filter code.
getTime()
Function to convert the time tag from samples since station midnight to seconds since station midnight. This function needs to dp_common module in order to work.
setCentralFreq(centralFreq)
Function to set the central frequency of the TBN data in Hz.
setGain(gain)
Function to set the gain of the TBN data.
setSampleRate(sampleRate)
Function to set the sample rate of the TBN data in Hz.
class lsl.reader.tbn.Frame(header=<lsl.reader.tbn.FrameHeader object at 0x2bd6350>, data=<lsl.reader.tbn.FrameData object at 0x2bd63d0>)

Class that stores the information contained within a single TBN frame. It’s properties are FrameHeader and FrameData objects.

getFilterCode()
Convenience wrapper for the Frame.FrameData.getFilterCode function.
getTime()
Convenience wrapper for the Frame.FrameData.getTime function.
parseID()
Convenience wrapper for the Frame.FrameHeader.parseID function.
setCentralFreq(centralFreq)
Convenience wrapper for the Frame.FrameData.setCentralFreq function.
setGain(gain)
Convenience wrapper for the Frame.FrameData.setGain function.
setSampleRate(sampleRate)
Convenience wrapper for the Frame.FrameData.setSampleRate function.
lsl.reader.tbn.readFrame(filehandle, SampleRate=None, CentralFreq=None, Gain=None, Verbose=False)
Function to read in a single TBN frame (header+data) and store the contents as a Frame object. This function wraps readerHeader and readData.
lsl.reader.tbn.readBlock(filehandle, nFrames=512, SampleRate=None, CentralFreq=None, Gain=None, Verbose=False)
Function to read in a single TBW block (frames set by the nFrames keyword) and store the contents as a ObservingBlock object. This function wraps readFrame.
lsl.reader.tbn.getSampleRate(filehandle, nFrames=None, FilterCode=False)
Find out what the sampling rate/filter code is from consecutive sets of observations. By default, the rate in Hz is returned. However, the corresponding filter code can be returned instead by setting the FilterCode keyword to true.
lsl.reader.tbn.getFramesPerObs(filehandle)
Find out how many frames are present per observation by examining the first 512 TBN frames. Return the number of frames per observations as a two- element tuple, one for each polarization.

DRX

Python module to read in DRX data. This module defines the following classes for storing the DRX data found in a file:

Frame

object that contains all data associated with a particular DRX frame. The primary constituents of each frame are:

  • FrameHeader - the DRX frame header object and
  • FrameData - the DRX frame data object.

Combined, these two objects contain all of the information found in the original DRX frame.

ObservingBlock
object that stores a collection of Frames for all beams/tunnings/ polarizations for a particular time.
The functions defined in this module fall into two class:
  1. convert a frame in a file to a Frame object and
  2. describe the format of the data in the file.

For reading in data, use the readFrame function. It takes a python file- handle as an input and returns a fully-filled Frame object. The readBlock function reads in a (user-defined) number of DRX frames and returns a ObservingBlock object.

For describing the format of data in the file, two function are provided:

getBeamCount
read in the first few frames of an open file handle and return how many beams are present in the file.
getFramesPerObs
read in the first several frames to see how many frames (tunnings/polarizations) are associated with each beam.

Finally, there are also two experimental functions defined in this file for averaging DRX observations. averageObservations performs a straight channel- by-channel average of a collection of DRX frames, which averageObservations2 allows for both temporal and spatial averaging.

class lsl.reader.drx.FrameHeader(frameCount=None, drxID=None, secondsCount=None, decimation=None, timeOffset=None, raw=None)

Class that stores the information found in the header of a DRX frame. All six fields listed in the DP IDC version H are stored as well as the original binary header data.

getSampleRate()
Return the sample rate of the data in samples/second.
parseID()
Parse the DRX ID into a tuple containing the beam (1 through 4), tunning (1 and 2), and polarization (0 and 1).
class lsl.reader.drx.FrameData(timeTag=None, flags=None, iq=None)

Class that stores the information found in the data section of a DRX frame. All three fields listed in the DP IDC version H are stored.

getTime()
Function to convert the time tag from samples since station midnight to seconds since station midnight. This function needs the dp_common module in order to work.
class lsl.reader.drx.Frame(header=<lsl.reader.drx.FrameHeader object at 0x2bd6ad0>, data=<lsl.reader.drx.FrameData object at 0x2bd6b50>)

Class that stores the information contained within a single DRX frame. It’s properties are FrameHeader and FrameData objects.

getSampleRate()
Convenience wrapper for the Frame.FrameHeader.getSampleRate function.
getTime()
Convenience wrapper for the Frame.FrameData.getTime function.
parseID()
Convenience wrapper for the Frame.FrameHeader.parseID function.
class lsl.reader.drx.ObservingBlock(x1=<lsl.reader.drx.Frame object at 0x2bd6b90>, y1=<lsl.reader.drx.Frame object at 0x2bd6c10>, x2=<lsl.reader.drx.Frame object at 0x2bd6c50>, y2=<lsl.reader.drx.Frame object at 0x2bd6c90>)
Class that stores all frames associates with a particular beam at a particular time.
lsl.reader.drx.readFrame(filehandle, Verbose=False)
Function to read in a single DRX frame (header+data) and store the contents as a Frame object. This function wraps readerHeader and readData.
lsl.reader.drx.readBlock(filehandle)
Function to read in a single DRX block (four frames) and store the contents as a ObservingBlock object. This function wraps readFrame.
lsl.reader.drx.getBeamCount(filehandle)
Find out how many beams are present by examining the first 16 DRX records. Return the number of beams found.
lsl.reader.drx.getFramesPerObs(filehandle)
Find out how many frames are present per beam by examining the first 16 DRX records. Return the number of frames per observations as a four- element tuple, one for each beam.

Reader Error Codes

Module that contains the error classes for the DRX, TBN, and TBW readers. These errors are currently meant to deal with file I/O problems.

exception lsl.reader.errors.baseReaderError(strerror, errno='-1')
Base class for file I/O problem during numpy.fromfile calls and out-of- sync Mark5C headers.
exception lsl.reader.errors.eofError
Extension to the base class for dealing with EOF errors. The error code is 1.
exception lsl.reader.errors.numpyError
Extension to the base class for dealing with errors that occur when numpy.fromfile tried to read more data can exists. This is a specialized form of EOF error. The error code is 2.
exception lsl.reader.errors.syncError(sync1=None, sync2=None, sync3=None, sync4=None)
Extension to the base class for dealing with Mark 5C header sync word problems. If the sync word doesn’t match what is expected. The error code is 3.
exception lsl.reader.errors.notTBNError
Extenstion to the base class for dealing with trying to read in TBW data with a TBN reader. The error code is 4.
exception lsl.reader.errors.notTBWError
Extenstion to the base class for dealing with trying to read in TBN data with a TBW reader. The error code is 5.
lsl.reader.errors.listErrorCodes(errno=None)
Function to provide a list of errors defined in this file. It alternatively takes an error code using the ‘errno’ keyword and returns its description.

Reader Ring Buffer

Buffer for dealing with out-of-order/missing frames.

class lsl.reader.buffer.FrameBuffer(stands=[], pols=[], beams=[], tunes=[])

Bases: object

Frame buffer for re-ordering TBN and DRX frames in time order. This class is filled with frames and a returns a frame list when either:

  • the buffer contains all frames for a given time, or
  • another has started to be filled and has more than 50 frames in it.

The buffer also keeps track of what has already been read out so that tardy frames are just dropped. For buffers that are read out, missing frames are replaced with frames filled with zeros.

append(frame)
Append a new frame to the buffer with the appropriate time tag. True is returned if the frame was added to the buffer and False if the frame was dropped.
get()
Return a list of frames that consitute a ‘full’ buffer. Afterwards, delete that buffer.
status()
Print out the status of the buffer.
class lsl.reader.buffer.TBNFrameBuffer(stands=[], pols=[, 0, 1])

Bases: lsl.reader.buffer.FrameBuffer

A sub-type of FrameBuffer specifically for dealing with TBN frames. See FrameBuffer for a description of how the buffering is implemented.

class lsl.reader.buffer.DRXFrameBuffer(beams=[], tunes=[, 1, 2], pols=[, 1, 2])

Bases: lsl.reader.buffer.FrameBuffer

A sub-type of FrameBuffer specifically for dealing with DRX frames. See FrameBuffer for a description of how the buffering is implemented.

class lsl.reader.buffer.TBWFrameBuffer(stands=[], nFrames=None)

Bases: object

Frame buffer for re-ordering TBW frames in time order. This class is filled with frames and a returns a frame list when either:

  • the buffer contains all frames for a given time, or
  • another has started to be filled and has more than 5 frames in it.

The buffer also keeps track of what has already been read out so that tardy frames are just dropped. For buffers that are read out, missing frames are replaced with frames filled with zeros.

TBW cannot be treated in the same way as TBN and DRX because of how the packets are sent out by DP, i.e., in stands pairs rather than by time.

append(frame)
Append a new frame to the buffer with the appropriate time tag. True is returned if the frame was added to the buffer and False if the frame was dropped.
get()
Return a list of frames that consitute a ‘full’ buffer. Afterwards, delete that buffer.
status()
Print out the status of the buffer.

Table Of Contents

Previous topic

Station Meta-Data

Next topic

Data Writers

This Page