Correlation

Python module to handle the channelization and cross-correlation of TBW and TBN data. The main python functions in this module are:

• calcSpectra - calculate power spectra for a collection of signals
• FXCorrelator - calculate cross power spectra for a collection of signals

both of which have been deprecated in favor of the new C extension based routines listed below.

The main python/C extension functions in this module are:

• SpecMaster - similar to calcSpectra but uses the _spec module for all computations and does not support automatic sub-integration
• SpecMasterP - SpecMaster with a 64-tap uniform DFT filter bank
• FXMaster - calculate cross power spectra for a collection of signals

Each function is set up to process the signals in parallel using the multiprocessing module and accepts a variety of options controlling the processing of the data, including various window functions and time averaging.

Baseline Utilities

lsl.correlator.uvUtils.getBaselines(antennas, IncludeAuto=False, Indicies=False)

Generate a list of two-element tuples that describe which antennae compose each of the output uvw triplets from computeUVW/computeUVTrack. If the Indicies keyword is set to True, the two-element tuples contain the indicies of the stands array used, rather than the actual stand numbers.

lsl.correlator.uvUtils.baseline2antenna(baseline, antennas, BaselineList=None, IncludeAuto=False, Indicies=False)

Given a baseline number, a list of stands, and options of how the base- line listed was generated, convert the baseline number to antenna numbers. Alternatively, use a list of baselines instead of generating a new list. This utility is useful for figuring out what antennae comprise a baseline.

lsl.correlator.uvUtils.antenna2baseline(ant1, ant2, antennas, BaselineList=None, IncludeAuto=False, Indicies=False)

Given two antenna numbers, a list of stands, and options to how the base- line listed was generated, convert the antenna pair to a baseline number. This utility is useful for picking out a particular pair from a list of baselines.

Computing uvw Coordinates

lsl.correlator.uvUtils.computeUVW(antennas, HA=0.0, dec=34.07, freq=49000000.0, IncludeAuto=False)

Compute the uvw converate of a baselines formed by a collection of stands. The coverage is computed at a given HA (in hours) and declination (in degrees) for LWA-1. The frequency provided (in Hz) can either as a scalar or as a numpy array. If more than one frequency is given, the output is a three dimensional with dimensions of baselines, uvw, and frequencies.

Changed in version 0.4.0: Switched over to passing in Antenna instances generated by the lsl.common.station module instead of a list of stand ID numbers.

lsl.correlator.uvUtils.computeUVTrack(antennas, dec=34.07, freq=49000000.0)

Whereas computeUVW provides the uvw coverage at a particular time, computeUVTrack provides the complete uv plane track for a long integration. The output is a three dimensional numpy array with dimensions baselines, uv, and 512 points along the track ellipses. Unlike computeUVW, however, only a single frequency (in Hz) can be specified.

Changed in version 0.4.0: Switched over to passing in Antenna instances generated by the lsl.common.station module instead of a list of stand ID numbers.

Polyphase Filter Bank

This module implements a uniform DFT filter bank for use in calculating spectra as an alternative to a simple FFT. The implementation here is based on: http://www.scribd.com/doc/20561850/6/Polyphase-Filter-Coef%EF%AC%81cients

lsl.correlator.filterbank.fft(signal, N, P=1, window=<function noWindow at 0x3122b90>)

FFT-based poly-phase filter bank for creating N channels with P taps. Optionally, a window function can be specified using the ‘window’ keyword. See lsl.correlator.fx.calcSpectra for details on using window functions.

lsl.correlator.filterbank.fft2(signal, N, window=<function noWindow at 0x3122b90>)

Sub-type of lsl.correlator.filterbank.fft that uses two taps.

lsl.correlator.filterbank.fft4(signal, N, window=<function noWindow at 0x3122b90>)

Sub-type of lsl.correlator.filterbank.fft that uses four taps.

lsl.correlator.filterbank.fft8(signal, N, window=<function noWindow at 0x3122b90>)

Sub-type of lsl.correlator.filterbank.fft that uses eight taps.

lsl.correlator.filterbank.fft16(signal, N, window=<function noWindow at 0x3122b90>)

Sub-type of lsl.correlator.filterbank.fft that uses 16 taps.

lsl.correlator.filterbank.fft32(signal, N, window=<function noWindow at 0x3122b90>)

Sub-type of lsl.correlator.filterbank.fft that uses 32 taps.

FX Correlator

lsl.correlator.fx.noWindow(L)

Default “empty” windowing function for use with the various routines. This function returned a numpy array of ‘1’s of the specified length.

lsl.correlator.fx.FXMaster(signals, antennas, LFFT=64, Overlap=1, IncludeAuto=False, verbose=False, window=<function noWindow at 0x3122b90>, SampleRate=None, CentralFreq=0.0, GainCorrect=False, ClipLevel=0)

A more advanced version of FXCorrelator for TBW and TBN data. Given an 2-D array of signals (stands, time-series) and an array of stands, compute the cross-correlation of the data for all baselines. Return the frequencies and visibilities as a two-elements tuple.

Changed in version 0.4.0: Switched over to passing in Antenna instances generated by the lsl.common.stations module instead of a list of stand ID numbers.

Deprecated

lsl.correlator.fx.correlate(signal1, signal2, antenna1, antenna2, LFFT=64, Overlap=1, window=<function noWindow at 0x3122b90>, verbose=False, SampleRate=None, CentralFreq=0.0)

Channalize and cross-correlate signals from two antennae. Both the signals and the stand numbers are needed to implement time delay and phase corrections. The resulting visibilities from the cross-correlation are time average and a LFFT-1 length numpy array is returned. This array does not contain the DC component of the signal.

lsl.correlator.fx.FXCorrelator(signals, antennas, LFFT=64, Overlap=1, IncludeAuto=False, window=<function noWindow at 0x3122b90>, CrossPol=None, DisablePool=False, verbose=False, SampleRate=None, CentralFreq=0.0)

A basic FX correlators for the TBW data. Given an 2-D array of signals (stands, time-series) and an array of stands, compute the cross-correlation of the data for all baselines. If cross-polarizations need to be calculated, the CrossPol keyword allows for the other polarization data to be entered into the correlator. Return the frequencies and visibilities as a two-elements tuple.

Deprecated since version 0.3.4: FXCorrelator has been deprecated as of LSL version 0.4.0 in favor of the new C-based correlator “FXMaster”. The new correlator, however, does not currently support windowing the data.

Changed in version 0.3.4: Prior to LSL version 0.4.0, the window functions available for FXCorrelator were limited to Blackman and an (untest) Polyphase filter. With version 0.4.0, the window to be used is passed to the function call via the ‘window’ keyword and an “empty” window is provided by the module. This allows for the various window function defined in numpy (i.e., bartlett, blackman, hamming, etc.) to be used. It also makes it easier to filter the data using a custom window. For example, a Kaiser window with a shape factor of 5 could be made with:

>>> import numpy
>>> def newWindow(L):
...      return numpy.kaiser(L, 5)

Changed in version 0.4.0: Switched over to passing in Antenna instances generated by the lsl.common.stations module instead of a list of stand ID numbers.

Visibility Visualization

Module of methods for visualizing visibility data. Routines include:

• plots of visibility amplitude as a function of uv radius
• plots of phase for specific baselines as a function of time
• plots of closure phase for three antennae as a function of time

In addition, most of the functions have the ability to compare the observed data with simulations. The data dictionaries referred to in the functions are in the formate as the data dictionaries created by lsl.sim.vis.

See also

lsl.sim.vis

lsl.correlator.visUtils.argument(data)

Return the argument (phase) of a complex number. This function is a ‘short cut’ for the numpy.angle function.

lsl.correlator.visUtils.unwrap(theta)

Given a numpy array of phases (complex number arguments), unwrap the phases by looking for +/- pi jumps in the data. Return an unwrapped numpy array of the same length.

lsl.correlator.visUtils.unmaskCompressedData(data, mask)

Given a numpy array that has been compressed and the mask used to compress it, rebuild the original full-sized array. Values that were previously masked are replaced with NaNs.

lsl.correlator.visUtils.plotVisibilities(dataDict, pol='yy', chan=None, jd=None, simDict=None, SaveFig=False)

Given a data dictionary from readUVData, create a plot of visibility amplitude as a function of uv radius. Alternately, a Julian Date can be specified and only data matched that date are plotted. If a dictionary of simulated data are also supplied via the simDict keyword, a two-panel plot is created comparing the real and simulated data.

lsl.correlator.visUtils.plotPhases(dataDict, baselines=[, 0], pol='yy', jd=None, stands=None, simDict=None, Unwrap=False, SaveFig=False)

Given a data dictionary from readUVData, create a plot of visibility phase as a function of frequency. If a dictionary of simulated data are also supplied via the simDict keyword, a two-panel plot is created comparing the real and simulated data.

lsl.correlator.visUtils.fitPhases(dataDict, simDict, baseline=0, pol='yy', minCorr=0.90000000000000002, returnDispersion=False, stands=None, NoPlot=False)

Given a data dictionary from readUVData, fit delays by examining the change of the visiblility phases with frequency. This routine examines each baseline of interest and looks for flat regions that are 3 MHz wide and have R correlation values greater than ‘minCorr’. In theses flat regions, a line is fit to the data and average slope found from the fits yields a delay. The delays are returned as a numpy array with values in ns. If the returnDispersion keyword is set, a numpy array with the standard deviation of the fits is also returned.

lsl.correlator.visUtils.plotClosure(dataDict, pol='yy', antennas=[, 1, 2, 3], individualPhases=False, stands=None, SaveFig=False)

Given a data dictionary from readUVData, plot the closure phase of three antennae as a function of time. If the individualPhases keyword is set, also plot the phases over time of the three antennae that comprise the closure triplet.