Data Readers

LSL Developer Primitives

class lsl.reader.ldp.TBWFile(filename=None, fh=None, ignoreTimeTagErrors=False)

Class to make it easy to interface with a TBW file. Methods defined for this class are: * getInfo - Get information about the file’s contents * getRemainingFrameCount - Get the number of frames remaining in the file * readFrame - Read and return a single lsl.reader.tbw.Frame instance * read - Read in the capture and return it as a numpy array

read(duration=None, timeInSamples=False)

Read and return the entire TBW capture. This function returns a three-element tuple with elements of: 0) the actual duration of data read in, 1) the time tag for the first sample, and 2) a 2-D Numpy array of data.

The time tag is returned as seconds since the UNIX epoch by default. However, the time tags can be returns as samples at fS if the timeInSamples keyword is set.

The sorting order of the output data array is by digitizer number - 1.

Note

Setting the ‘duration’ keyword has no effect on the read process because the entire capture is always read in.

readFrame()

Read and return a single lsl.reader.tbw.Frame instance.

class lsl.reader.ldp.TBNFile(filename=None, fh=None, ignoreTimeTagErrors=False)

Class to make it easy to interface with a TBN file. Methods defined for this class are: * getInfo - Get information about the file’s contents * getRemainingFrameCount - Get the number of frames remaining in the file * offset - Offset a specified number of seconds into the file * readFrame - Read and return a single lsl.reader.tbn.Frame instance * read - Read a chunk of data in and return it as a numpy array * estimateLevels - Estimate the n-sigma level for the absolute value of the voltages

estimateLevels(nFrames=100, Sigma=5.0)

Estimate the n-sigma level for the absolute value of the voltages. Returns a list with indicies that are the digitizer numbers minus one.

offset(offset)

Offset a specified number of seconds in an open TBN file. This function returns the exact offset time.

Note

The offset provided by this function is relatively crude due to the structure of TBN files.

Changed in version 1.2.4: Offsets are now relative to the current location in the file rather than to the start of the file

read(duration, timeInSamples=False)

Read in a chunk (in seconds) of TBN data. This function returns a three-element tuple with elements of: 0) the actual duration of data read in, 1) the time tag for the first sample, and 2) a 2-D Numpy array of data.

The time tag is returned as seconds since the UNIX epoch by default. However, the time tags can be returns as samples at fS if the timeInSamples keyword is set.

The sorting order of the output data array is by digitizer number - 1.

readFrame()

Read and return a single lsl.reader.tbn.Frame instance.

class lsl.reader.ldp.DRXFile(filename=None, fh=None, ignoreTimeTagErrors=False)

Class to make it easy to interface with a DRX file. Methods defined for this class are: * getInfo - Get information about the file’s contents * getRemainingFrameCount - Get the number of frames remaining in the file * offset - Offset a specified number of seconds into the file * readFrame - Read and return a single lsl.reader.drx.Frame instance * read - Read a chunk of data in and return it as a numpy array * estimateLevels - Estimate the n-sigma level for the absolute value of the voltages

estimateLevels(nFrames=100, Sigma=5.0)

Estimate the n-sigma level for the absolute value of the voltages. Returns a list with indicies corresponding to: 0) Tuning 1, X pol. 1) Tuning 1, Y pol. 2) Tuning 2, X pol. 3) Tuning 2, Y pol.

..note::
The returned list always has four items, regardless of whether or not the input DRX file has one or two tunings.
offset(offset)

Offset a specified number of seconds in an open DRX file. This function returns the exact offset time.

read(duration, timeInSamples=False)

Given an open DRX file and an amount of data to read in in seconds, read in the data and return a three-element tuple of the actual duration read in, the time for the first sample, and the data as numpy array.

..note::
This function always returns a 2-D array with the first dimension holding four elements. These elements contain, in order: * Tuning 1, polarization X * Tuning 1, polarization Y * Tuning 2, polarization X * Tuning 2, polarization Y
readFrame()

Read and return a single lsl.reader.drx.Frame instance.

class lsl.reader.ldp.DRSpecFile(filename=None, fh=None, ignoreTimeTagErrors=False)

Class to make it easy to interface with a DR Spectrometer file. Methods defined for this class are: * getInfo - Get information about the file’s contents * getRemainingFrameCount - Get the number of frames remaining in the file * offset - Offset a specified number of seconds into the file * readFrame - Read and return a single lsl.reader.drspec.Frame instance * read - Read a chunk of data in and return it as a numpy array

offset(offset)

Offset a specified number of seconds in an open DR spectrometer file. This function returns the exact offset time.

read(duration, timeInSamples=False)

Given an open DR spectrometer file and an amount of data read in in seconds, read in the data and return a three-element tuple of the actual duration read in, the times at the beginning of each stream, and the data as numpy array.

..note::
This function always returns a 3-D array with the first dimension indexing over data product, the second over time and the third over frequency channel.
readFrame()

Read and return a single lsl.reader.drspec.Frame instance.

class lsl.reader.ldp.TBFFile(filename=None, fh=None, ignoreTimeTagErrors=False)

Class to make it easy to interface with a TBF file. Methods defined for this class are: * getInfo - Get information about the file’s contents * getRemainingFrameCount - Get the number of frames remaining in the file * offset - Offset a specified number of seconds into the file * readFrame - Read and return a single lsl.reader.tbw.Frame instance * read - Read in the capture and return it as a numpy array

offset(offset)

Offset a specified number of seconds in an open TBF file. This function returns the exact offset time.

Note

The offset provided by this function is relatively crude due to the structure of TBF files.

Changed in version 1.2.4: Offsets are now relative to the current location in the file rather than to the start of the file

read(duration=None, timeInSamples=False)

Read and return the entire TBF capture. This function returns a three-element tuple with elements of: 0) the actual duration of data read in, 1) the time tag for the first sample, and 2) a 3-D Numpy array of data.

The time tag is returned as seconds since the UNIX epoch by default. However, the time tags can be returns as samples at fS if the timeInSamples keyword is set.

The sorting order of the output data array is by digitizer number - 1.

readFrame()

Read and return a single lsl.reader.tbf.Frame instance.

lsl.reader.ldp.LWA1DataFile(filename=None, fh=None, ignoreTimeTagErrors=False)

Wrapper around the various LWA1-related classes defined here that takes a file, determines the data type, and initializes and returns the appropriate LDP class.

lsl.reader.ldp.LWASVDataFile(filename=None, fh=None, ignoreTimeTagErrors=False)

Wrapper around the various LWA-SV-related classes defined here that takes a file, determines the data type, and initializes and returns the appropriate LDP class.

lsl.reader.ldp.LWADataFile(filename=None, fh=None, ignoreTimeTagErrors=False)

Wrapper around the various classes defined here that takes a file, determines the data type, and initializes and returns the appropriate LDP class.

Low-Level TBW – DP

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.

Changed in version 0.4.0: Switched over from pure Python readers to the new C-base Go Fast! readers.

class lsl.reader.tbw.FrameHeader(frameCount=None, secondsCount=None, tbwID=None)

Class that stores the information found in the header of a TBW frame. All three fields listed in the DP ICD 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 ICD version H are stored.

getTime()

Function to convert the time tag from samples since the UNIX epoch (UTC 1970-01-01 00:00:00) to seconds since the UNIX epoch.

class lsl.reader.tbw.Frame(header=None, data=None)

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.

isTBW()

Convenience wrapper for the Frame.FrameHeader.isTBW 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 260 stands. This is done by reading two frames and then skipping the next 30,000.

Note

Post-IOC it is probably simpler to adopt a value of the number of frames per observation of 260 rather than try to find it from the file.

Low-Level TBF – ADP

New in version 1.2.

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

Frame

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

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

Combined, these two objects contain all of the information found in the original TBF 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.

New in version 1.2.0.

class lsl.reader.tbf.FrameHeader(id=None, frameCount=None, secondsCount=None, firstChan=None)

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

getChannelFreqs()

Return a numpy.float32 array for the center frequencies, in Hz, of each channel in the data.

isTBF()

Function to check if the data is really TBF. Returns True if the data is TBF, false otherwise.

class lsl.reader.tbf.FrameData(timeTag=None, fDomain=None)

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

getTime()

Function to convert the time tag from samples since the UNIX epoch (UTC 1970-01-01 00:00:00) to seconds since the UNIX epoch.

class lsl.reader.tbf.Frame(header=None, data=None)

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

getChannelFreqs()

Convenience wrapper for the Frame.FrameHeader.getChannelFreqs function.

getTime()

Convenience wrapper for the Frame.FrameData.getTime function.

isTBF()

Convenience wrapper for the Frame.FrameHeader.isTBF function.

lsl.reader.tbf.readFrame(filehandle, Verbose=False)

Function to read in a single TBF frame (header+data) and store the contents as a Frame object.

lsl.reader.tbf.getFramesPerObs(filehandle)

Find out how many frames are present per time stamp by examining the first 1000 TBF records. Return the number of frames per observation.

lsl.reader.tbf.getFirstFrameCount(filehandle)

Find and return the lowest frame count encountered in a TBF file.

lsl.reader.tbf.getChannelCount(filehandle)

Find out the total number of channels that are present by examining the first 1000 TBF records. Return the number of channels found.

lsl.reader.tbf.getFirstChannel(filehandle, frequency=False)

Find and return the lowest frequency channel in a TBF file. If the frequency keyword is True the returned value is in Hz.

Low-Level TBN – DP and ADP

class lsl.reader.tbn.FrameHeader(frameCount=None, tuningWord=None, tbnID=None, gain=None)

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

Changed in version 0.5.0: Added various attributes to retrieve the central frequnecy and gain that are part of the ECR 11 changes.

getCentralFreq()

Convert the tuning word to a frequency in Hz.

getFilterCode()

Function to convert the sample rate in Hz to a filter code.

getGain()

Get the current TBN gain for this frame.

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.

setSampleRate(sampleRate)

Function to set the sample rate of the TBN data in Hz.

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 ICD version H are stored.

Changed in version 0.5.0: Removed various attributes related to storing a central frequnecy and gain that aren’t needed with ECR 11.

getTime()

Function to convert the time tag from samples since the UNIX epoch (UTC 1970-01-01 00:00:00) to seconds since the UNIX epoch.

class lsl.reader.tbn.Frame(header=None, data=None)

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

Changed in version 0.5.0: Removed various attributes related to storing a central frequnecy and gain that aren’t needed with ECR 11.

getCentralFreq()

Convenience wrapper for the Frame.FrameHeader.getCentralFreq function.

getFilterCode()

Convenience wrapper for the Frame.FrameData.getFilterCode function.

getGain()

Convenience wrapper for the Frame.FrameHeader.getGain function.

getTime()

Convenience wrapper for the Frame.FrameData.getTime function.

isTBN()

Convenience wrapper for the Frame.FrameHeader.isTBN function.

parseID()

Convenience wrapper for the Frame.FrameHeader.parseID function.

setSampleRate(sampleRate)

Convenience wrapper for the Frame.FrameData.setSampleRate function.

lsl.reader.tbn.readFrame(filehandle, SampleRate=None, Verbose=False)

Function to read in a single TBN frame (header+data) and store the contents as a Frame object.

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 2,080 TBN frames. Return the number of frames per observations as a two- element tuple, one for each polarization.

So many TBN frames are read in order to try to compensate for the inter- leaving of the packets from the various DP1 boards during the recording.

Note

Post-IOC it is probably simpler to adopt a value of the number of frames per observation of 520 rather than try to find it from the file.

Low-Level COR – ADP

New in version 1.2.

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

Frame

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

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

Combined, these two objects contain all of the information found in the original COR 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.

Changed in version 1.2.1: Updated for the switch over to 72 channels, complex64 data, and no data weights

New in version 1.2.0.

class lsl.reader.cor.FrameHeader(id=None, frameCount=None, secondsCount=None, firstChan=None, gain=None)

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

getChannelFreqs()

Return a numpy.float32 array for the center frequencies, in Hz, of each channel in the data.

getGain()

Get the current TBN gain for this frame.

isCOR()

Function to check if the data is really COR. Returns True if the data is COR, false otherwise.

class lsl.reader.cor.FrameData(timeTag=None, nAvg=None, stand0=None, stand1=None, vis=None)

Class that stores the information found in the data section of a COR frame.

getIntegrationTime()

Return the integration time of the visibility in seconds.

getTime()

Function to convert the time tag from samples since the UNIX epoch (UTC 1970-01-01 00:00:00) to seconds since the UNIX epoch.

parseID()

Return a tuple of the two stands that contribute the this frame.

class lsl.reader.cor.Frame(header=None, data=None)

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

getChannelFreqs()

Convenience wrapper for the Frame.FrameHeader.getChannelFreqs function.

getGain()

Convenience wrapper for the Frame.FrameHeader.getGain function.

getIntegrationTime()

Convenience wrapper for the Frame.FrameData.getIntegrationTime function.

getTime()

Convenience wrapper for the Frame.FrameData.getTime function.

isCOR()

Convenience wrapper for the Frame.FrameHeader.isCOR function.

parseID()

Convenience wrapper for the Frame.FrameData.parseID function.

lsl.reader.cor.readFrame(filehandle, Verbose=False)

Function to read in a single COR frame (header+data) and store the contents as a Frame object.

lsl.reader.cor.getFramesPerObs(filehandle)

Find out how many frames are present per time stamp by examining the first several COR records. Return the number of frames per observation.

lsl.reader.cor.getChannelCount(filehandle)

Find out the total number of channels that are present by examining the first several COR records. Return the number of channels found.

lsl.reader.cor.getBaselineCount(filehandle)

Find out the total number of baselines that are present by examining the first several COR records. Return the number of baselines found.

Low-Level DRX – DP and ADP

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/tunings/ 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 (tunings/polarizations) are associated with each beam.
..versionchanged:: 1.2.0
Dropped support for ObservingBlock since the lsl.reader.buffer modules does a better job.

Changed in version 0.4.0: Switched over from pure Python readers to the new C-base Go Fast! readers.

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

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

getFilterCode()

Function to convert the sample rate in Hz to a filter code.

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, tuningWord=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 ICD version H are stored.

getCentralFreq()

Function to set the central frequency of the DRX data in Hz.

setGain(gain)

Function to set the gain of the DRX data.

class lsl.reader.drx.Frame(header=None, data=None)

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

getCentralFreq()

Convenience wrapper for the Frame.FrameData.getCentralFreq function.

getFilterCode()

Convenience wrapper for the Frame.FrameHeader.getFilterCode function.

getSampleRate()

Convenience wrapper for the Frame.FrameHeader.getSampleRate function.

getTime()

Function to convert the time tag from samples since the UNIX epoch (UTC 1970-01-01 00:00:00) to seconds since the UNIX epoch.

parseID()

Convenience wrapper for the Frame.FrameHeader.parseID function.

setGain(gain)

Convenience wrapper for the Frame.FrameData.setGain function.

lsl.reader.drx.readFrame(filehandle, Gain=None, 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.getSampleRate(filehandle, nFrames=None, FilterCode=False)

Find out what the sampling rate/filter code is from a single 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.

This function is included to make easier to write code for TBN analysis and modify it for DRX data.

lsl.reader.drx.getBeamCount(filehandle)

Find out how many beams are present by examining the first 32 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 32 DRX records. Return the number of frames per observations as a four- element tuple, one for each beam.

Low-Level DRX8 – ADP

Low-Level DR Spectrometer – DP and ADP

New in version 0.5.

class lsl.reader.drspec.FrameHeader(beam=0, format=0, decimation=None, timeOffset=None, nInts=None)

Class that stores the information found in the header of a DR spectrometer/DRX frame.

containsLinearData()

Return whether or not the frame contains linear polarization products or not.

New in version 0.6.0.

containsStokesData()

Return whether or not the frame contains Stokes polarization parameters or not.

New in version 0.6.0.

getDataProducts()

Return a list of data products contained in the file.

New in version 0.6.0.

getFFTsPerIntegration()

Return the number of FFT windows per integration.

New in version 1.0.1.

getFilterCode()

Function to convert the sample rate in Hz to a filter code.

getSampleRate()

Return the sample rate of the data in samples/second.

parseID()

Return the beam the frame corresponds to.

class lsl.reader.drspec.FrameData(timeTag=None, tuningWords=None, fills=None, errors=None, saturations=None)

Class that stores the information found in the data section of a DR spectrometer/ DRX frame.

Changed in version 0.5.3: Added the saturations field to keep up with saturation counts.

Changed in version 0.6.0: The attributes that store the data are not defined until a frame is read in order to account for the fact that spectrometer files can store either linear or Stokes data.

getCentralFreq(which=None)

Function to set the central frequency of the DRX data in Hz.

setGain(gain)

Function to set the gain of the DRX data.

class lsl.reader.drspec.Frame(header=None, data=None)

Class that stores the information contained within a single DR spectrometer/ DRX frame. It’s properties are FrameHeader and FrameDataLinear/FrameDataStokes objects.

Changed in version 0.6.0: By default the data contained with in a frame is normalized by the number of fills (header.fills parameter). For data products that are a function of more than one primary input, i.e., XY* or I, the minimum fill of X and Y are used for normalization.

containsLinearData()

Convenience wrapper for the Frame.FrameHeder.containsLinearData function.

containsStokesData()

Convenience wrapper for the Frame.FrameHeder.containsStokesData function.

getCentralFreq(which=None)

Convenience wrapper for the Frame.FrameData.getCentralFreq function.

getDataProducts()

Convenience wrapper for the Frame.FrameHeder.getDataProducts function.

getFFTsPerIntegration()

Conveinence wrapper for the Frame.FrameHeader.getFFTsPerIntegration function.

New in version 1.0.1.

getFilterCode()

Convenience wrapper for the Frame.FrameHeader.getFilterCode function.

getIntegrationTime()

Return the integration time for data in seconds.

New in version 1.0.1.

getSampleRate()

Convenience wrapper for the Frame.FrameHeader.getSampleRate function.

getTime()

Function to convert the time tag from samples since the UNIX epoch (UTC 1970-01-01 00:00:00) to seconds since the UNIX epoch.

getTransformSize()

Find out what the transform size is.

New in version 1.0.1.

parseID()

Convenience wrapper for the Frame.FrameHeader.parseID function.

setGain(gain)

Convenience wrapper for the Frame.FrameData.setGain function.

lsl.reader.drspec.readFrame(filehandle, Gain=None, Verbose=False)

Function to read in a single DR spectrometer/DRX frame (header+data) and store the contents as a Frame object.

lsl.reader.drspec.getDataProducts(filehandle)

Find out the data products contained in the file by looking at a frame.

lsl.reader.drspec.containsLinearData(filehandle)

Find out if the file contains linear polarization products or not.

lsl.reader.drspec.containsStokesData(filehandle)

Find out if the file contains Stokes parameters or not.

lsl.reader.drspec.getSampleRate(filehandle, nFrames=None, FilterCode=False)

Find out what the sampling rate/filter code is from a single 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.drspec.getFrameSize(filehandle)

Find out what the frame size in a file is at the current file location. Returns the frame size in bytes.

lsl.reader.drspec.getFFTsPerIntegration(filehandle)

Find out what the number of FFT windows per integration is at the current file location.

New in version 1.0.1.

lsl.reader.drspec.getTransformSize(filehandle)

Find out what the transform size in a file is at the current file location.

lsl.reader.drspec.getIntegrationTime(filehandle)

Find out what the integration time is at the current file location.

Low-Level VIDF

class lsl.reader.vdif.FrameHeader(isInvalid=0, isLegacy=0, secondsFromEpoch=0, refEpoch=0, frameInSecond=0, version=1, nChan=0, frameLength=0, isComplex='C', bitsPerSample=0, threadID=0, stationID=0, extendedData1=None, extendedData2=None, extendedData3=None, extendedData4=None, sampleRate=0.0, centralFreq=0.0)

Class that stores the information found in the header of a VDIF frame. Most fields in the VDIF version 1.1.1 header are stored.

getCentralFreq()

Function to get the central frequency of the VDIF data in Hz.

getSampleRate()

Return the sample rate of the data in samples/second.

getTime()

Function to convert the time tag to seconds since the UNIX epoch.

parseExtendedUserData()

Parse the extended user data if it was included with the reader. The data is returned as a dictionary.

parseID()

Return a two-element tuple of the station ID and thread ID.

Note

The station ID is always returned as numeric.

class lsl.reader.vdif.FrameData(data=None)

Class that stores the information found in the data section of a VDIF frame.

Note

Unlike the other readers in the lsl.reader module the data are stored as numpy.float32 values.

class lsl.reader.vdif.Frame(header=None, data=None)

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

getCentralFreq()

Convenience wrapper for the Frame.FrameHeader.getCentralFreq function.

getSampleRate()

Convenience wrapper for the Frame.FrameHeader.getSampleRate function.

getTime()

Convenience wrapper for the Frame.FrameHeader.getTime function.

parseExtendedUserData()

Convenience wrapper for the Frame.FrameHeader.parseExtendedUserData function.

parseID()

Convenience wrapper for the Frame.FrameHeader.parseID function.

lsl.reader.vdif.readGUPPIHeader(filehandle)

Read in a GUPPI header at the start of a VDIF file from the VLA. The contents of the header are returned as a dictionary.

lsl.reader.vdif.readFrame(filehandle, sampleRate=0.0, centralFreq=0.0, Verbose=False)

Function to read in a single VDIF frame (header+data) and store the contents as a Frame object. This function wraps the _readerHeader and _readData functions.

lsl.reader.vdif.getFrameSize(filehandle, nFrames=None)

Find out what the frame size is in bytes from a single observation.

lsl.reader.vdif.getThreadCount(filehandle)

Find out how many thrads are present by examining the first 1024 records. Return the number of threads found.

lsl.reader.vdif.getFramesPerSecond(filehandle)

Find out the number of frames per second in a file by watching how the headers change. Returns the number of frames in a second.

lsl.reader.vdif.getSampleRate(filehandle)

Find and return the sample rate in Hz by looking at how many frames there are per second and how many samples there are in a frame.

Reader Error Codes

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.syncError(location=None, 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

class lsl.reader.buffer.FrameBuffer(mode='TBN', stands=, []beams=, []tunes=, []pols=, []chans=, []threads=, []nSegments=6, ReorderFrames=False)

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 the ‘nSegments’ starts filling. In that case, the oldest segment is returned.

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.

Note

Due to the nature of the buffer, it is possible that there will still be ‘nSegments’-1 segements in the buffer that are either full or partially full. This can be retrieved using the buffer’s ‘flush()’ function.

append(frames)

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 because it belongs to a buffer that has already been returned.

calcFrames()

Calculate the maximum number of frames that we expect from the setup of the observations and a list of tuples that describes all of the possible stand/pol combination.

This will be overridden by sub-classes of FrameBuffer.

createFill(key, frameParameters)

Create a ‘fill’ frame of zeros using an existing good packet as a template.

This will be overridden by sub-classes of FrameBuffer.

figureOfMerit(frame)

Figure of merit for storing/sorting frames in the ring buffer.

This will be overridden by sub-classes of FrameBuffer.

filled

Indicates whether or not the ring buffer is full or not.

New in version 1.2.4.

flush()

Generator to return all of the remaining frames in the buffer from buffers that are considered ‘full’. Afterwards, delete all buffers. This is useful for emptying the buffer after reading in all of the data.

Note

It is possible for this function to return list of packets that are mostly invalid.

get(keyToReturn=None)

Return a list of frames that consitute a ‘full’ buffer. Afterwards, delete that buffer and mark it as closed so that any missing frames that are recieved late are dropped. If none of the buffers are ready to be dumped, None is returned.

isEmpty()

Determine if there is anything in the buffer or not. Returns False if there is, True if there is not.

overfilled

Indicates whether or not the ring buffer has too many segements or not.

New in version 1.2.4.

peek(require_filled=True)

Peek into the buffer to see what the next key to be retruned by a call to get() will be. Returns None if the buffer is not full and required_filled is True.

New in version 1.2.4.

put(*args, **kwds)

Synonymous with ‘append’.

reset()

Emtpy the contents of the buffer and reset it to a clean state.

status()
Print out the status of the buffer. This contains information about:
  1. The current buffer fill level
  2. The numer of full and partial buffer dumps preformed
  3. The number of missing frames that fill packets needed to be created for
  4. The number of frames that arrived too late to be incorporated into one of the ring buffers
class lsl.reader.buffer.TBNFrameBuffer(stands=[], pols=[0, 1], nSegments=20, ReorderFrames=False)

Bases: lsl.reader.buffer.FrameBuffer

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

Keywords:
stands
list of stand to expect packets for
pols
list of polarizations to expect packets for
nSegments
number of ring segments to use for the buffer (default is 20)
ReorderFrames
whether or not to reorder frames returned by get() or flush() by stand/polarization (default is False)

The number of segements in the ring can be converted to a buffer time in seconds:

Segments TBN Filter Code
1 2 3 4 5 6 7
10 5.1 1.6 0.8 0.4 0.2 0.1 0.05
20 10.2 3.3 1.6 0.8 0.4 0.2 0.10
30 15.4 4.9 2.5 1.2 0.6 0.3 0.15
40 20.5 6.6 3.3 1.6 0.8 0.4 0.20
50 25.6 8.2 4.1 2.0 1.0 0.5 0.26
100 51.2 16.4 8.2 4.1 2.0 1.0 0.51
calcFrames()

Calculate the maximum number of frames that we expect from the setup of the observations and a list of tuples that describes all of the possible stand/pol combination.

createFill(key, frameParameters)

Create a ‘fill’ frame of zeros using an existing good packet as a template.

figureOfMerit(frame)
Figure of merit for sorting frames. For TBN it is:
<frame timetag in ticks>
class lsl.reader.buffer.DRXFrameBuffer(beams=[], tunes=[1, 2], pols=[0, 1], nSegments=20, ReorderFrames=False)

Bases: lsl.reader.buffer.FrameBuffer

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

Keywords:
beams
list of beam to expect packets for
tunes
list of tunings to expect packets for
pols
list of polarizations to expect packets for
nSegments
number of ring segments to use for the buffer (default is 20)
ReorderFrames
whether or not to reorder frames returned by get() or flush() by stand/polarization (default is False)

The number of segements in the ring can be converted to a buffer time in seconds:

Segments DRX Filter Code
1 2 3 4 5 6 7
10 0.16 0.08 0.04 0.02 0.01 0.004 0.002
20 0.33 0.16 0.08 0.04 0.02 0.008 0.004
30 0.49 0.25 0.12 0.06 0.03 0.013 0.006
40 0.66 0.33 0.16 0.08 0.03 0.017 0.008
50 0.82 0.41 0.20 0.10 0.04 0.021 0.010
100 1.64 0.82 0.41 0.20 0.08 0.042 0.021
calcFrames()

Calculate the maximum number of frames that we expect from the setup of the observations and a list of tuples that describes all of the possible stand/pol combination.

createFill(key, frameParameters)

Create a ‘fill’ frame of zeros using an existing good packet as a template.

figureOfMerit(frame)
Figure of merit for sorting frames. For DRX it is:
<frame timetag in ticks>
class lsl.reader.buffer.TBFFrameBuffer(chans, nSegments=25, ReorderFrames=False)

Bases: lsl.reader.buffer.FrameBuffer

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

Keywords:
chans
list of start channel numbers to expect data for
nSegments
number of ring segments to use for the buffer (default is 25)
ReorderFrames
whether or not to reorder frames returned by get() or flush() by start channel (default is False)

The number of segements in the ring can be converted to a buffer time in seconds:

Segments Time
10 0.0004
25 0.001
50 0.002
100 0.004
200 0.008
calcFrames()

Calculate the maximum number of frames that we expect from the setup of the observations and a list of tuples that describes all of the possible stand/pol combination.

createFill(key, frameParameters)

Create a ‘fill’ frame of zeros using an existing good packet as a template.

figureOfMerit(frame)

Figure of merit for sorting frames. For TBF this is: frame.data.timeTag

class lsl.reader.buffer.VDIFFrameBuffer(threads=[0, 1], nSegments=10, ReorderFrames=False)

Bases: lsl.reader.buffer.FrameBuffer

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

Keywords:
threads
list of thread IDs to expect data for
nSegments
number of ring segments to use for the buffer (default is 10)
ReorderFrames
whether or not to reorder frames returned by get() or flush() by stand/polarization (default is False)
calcFrames()

Calculate the maximum number of frames that we expect from the setup of the observations and a list of tuples that describes all of the possible stand/pol combination.

createFill(key, frameParameters)

Create a ‘fill’ frame of zeros using an existing good packet as a template.

figureOfMerit(frame)

Figure of merit for sorting frames. For VIDF this is: secondsFromEpoch * 1000000 + frameInSecond