LWA Software Library Documentation¶

This package contains a collection of tools for reading, format shifting, and analyzing LWA data. It also contains the majority of the lwa_user library developed by NRL.

Contents¶

Installation¶

Requirements¶

python >= 2.7

fftw3 >= 3.2

gdbm >= 1.8

numpy >= 1.7

scipy >= 0.19

astropy < 3.0 (2.7) or >= 3.0 (3.0+)

ephem >= 3.7.5.3

aipy >= 3.0.1

pytz >= 2012c

matplotlib >= 1.1 1

BeautifulSoup 1

casacore 2

1(1,2): Required for some of the included scripts
2: Required for measurement set support

Installing¶

The LSL package is installed as a regular Python package using distutils. Unzip and untar the source distribution. Setup the python interpreter you wish to use for running the package applications and switch to the root of the source distribution tree.

Install LSL by running:

pip install . [--root=<prefix>|--user]

If the ‘–root’ option is not provided, then the installation tree root directory is the same as for the python interpreter used to run setup.py. For instance, if the python interpreter is in ‘/usr/local/bin/python’, then <prefix> will be set to ‘/usr/local’. Otherwise, the explicit <prefix> value is taken from the command line option. The package will install files in the following locations:

<prefix>/bin

<prefix>/lib/python2.6/site-packages

<prefix>/share/doc

<prefix>/share/install

If an alternate <prefix> value is provided, you should set the PATH environment to include directory ‘<prefix>/bin’ and the PYTHONPATH environment to include directory ‘<prefix>/lib/python2.6/site-packages’.

If the ‘–user’ option is provided, then then installation tree root directory will be in the current user’s home directory.

Unit Tests¶

Unit tests for the package may be found in the ‘lsl/tests’ sub-directory in the package source distribution tree. To run the complete suite of package unit tests:

cd tests
python -m unittest discover

Telemetry¶

By default LSL installs with basic telemetry enabled in order to help inform the LWA how the software is used and to help inform future development. The data collected as part of this consist seven things:

a timestamp for when the report is generated,

a unique installation identifier,

the LSL version being used,

the execution time of the Python process that imports LSL,

which LSL modules are imported,

which LSL functions are used and their average execution times, and

which LSL scripts are used.

These data are sent to the LWA using a HTTP POST request where they are aggregated.

Users can opt out of telemetry collection using the provided lslTelemetry.py script via:

python lslTelemetry.py --disable

This command will set a disk-based flag that disables the reporting process. This script can also be used to re-enable telemetry and check the unique installation identifier being used.

Release Notes¶

Version 2.0.1¶

Fixed a few problems with the scripts that ship with LSL

Added support for time zone-aware datetime instances in lsl.common.datetime_to_mjdmpm() and mjdmpm_to_datetime()

Added a utc_datetime attribute to lsl.reader.base.FrameTimestamp to provide a time zone-aware datetime instance

Dropped the requirement that a beam be specified in lsl.common.sdf and sdfADP

Fixed a deadlock condition that could occur during a DRXFile.offset()

Fixed a bug in the DRXFile when dealing with small gaps in the data

Updated lsl.reader.errors.SyncError to allow for reporting of non-Mark5C problems

Update the documentation for lsl.common.idf, sdf, and sdfADP

Added missing sub, isub, div, and idiv operators to lsl.reader.base.FrameBase

Added a jd property to lsl.reader.base.FrameTimestamp to access the associated Julian day

Updated the lsl.writer module to accept times as FrameTimestamp instances

Version 2.0.0¶

Major API changes to put LSL under a uniform coding style

Bumped the minimum Python version to 2.7

Bumped the mininum SciPy version to 0.13

Replaced PyFITS with astropy.io.fits

Removed support for 32-bit systems in the lsl.common modules

Added a new lsl.imaging.data module and classes to help store visibility data

Added a new extension to speed up w-projection gridding

Merged the non-windowed and windowed functions in the lsl.correlator extensions to de-duplicate some of the codebase

Added support for reading CASA measurement sets with multiple spectral windows

Added test suites for CASA measurement set support when the ‘casacore’ module is found

Added support for astorpy.units.quantity.Quantity instances to lsl.misc.rfutil

Updated the AIPY version requirement to >=3.0.1

Updated the scipy version requirement to >=0.19

Removed lsl.misc.mathutil.savitzky_golay since it was added in scipy v0.14.0+

Added support for collecting usage data for LSL via lsl.misc.telemetry

Updated to lsl.misc.ionosphere to IGRF13

Dropped support for PyFFTW

Older Versions¶

Version 1.2.6¶

Fixed a bug in the lsl.reader.ldp classes that causes offset() to fail in certain cases

Version 1.2.5¶

Updated setup.py to make it more likely that clang will build OpenMP-enabled extensions

Updated the install documentation to recommend pip

Added a 4-tap + Hanning windowed polyphase filter bank to the various functions in lsl.correlator.fx

Added an option to use the new PFB in correlateTBN and correlateTBW

Added an option to use the new PFB in drxSpectra, tbnSpectra, and tbwSpectra

Added support for proper motions to the IDF format

Added support for storing source intentions in the CALCODE field in FITS IDI files

Modified the offset method in lsl.reader.ldp to take into account the frame buffers

Added support to the lsl.reader.ldp.DRSpecFile object for jumping over bad data at the start of a file

Improved support for complex and multi-channel VDIF data

Added support for filter code 7 (19.6 MHz) on ADP

Added support for beam 3 on ADP

Version 1.2.4¶

Fixed a bug in driftcurve.py that put a cos(decliation) correction into the LFSM runs

Updated the documentation to reflect that unittest2 is now required as of 1.2.2 for Python 2.6 support

Added argparse as an extra dependency for Python 2.6

Moved the scripts that ship with LSL to argparse for command line parsing

Added a new lsl.misc.parser module to help with the switch over to argparse

Updated the minimum PyEphem version of 3.5.7.3

Fixed a bug in lsl.misc.ionosphere that causes some UQR files to fail to parse

Updated the URL/filename structure used to download the CODE files in lsl.misc.ionosphere

Added support for MCS MIBs stored as .gdb files

Added support for writing comments and history to FITS-IDI, SDFITS, and UVFITS files

Changed the lsl.reader.ldp.DRXFile class to deal with small (<50 frame) gaps in DRX files

Changed the lsl.reader.cor module to ensure the YX is valid for the autocorrelations

Worked on reduced the memory usage of the FITS-IDI writer

Adjusted the TBW duration calculation to reflect that DP can output TBW twice as fast now

Changed the lsl.common.sdf and lsl.common.sdfADF to allow “flat” Projects and Sessions

Fixed a problem triggering auto-copy in SDFs when not session comments are provided

Fixed a problem in some of the lsl.writer modules that caused duplicate entries to end up in SOURCE tables

Added support for interferometer definition files (IDFs)

Version 1.2.3¶

Fixed a problem with the conditional dependencies in setup.py for older versions of setuptools

Increased the default ring segment count for lsl.reader.buffer.DRXFrameBuffer to better deal with LWA-SV data

Increased the number of frames examined by lsl.reader.ldp.DRXFile to better deal with LWA-SV data

Version 1.2.2¶

Bumped the minimum PyFITS version to 3.2

Fixed a bug in setup.py that causes it to crash when ‘pkg-config’ is not installed

Fixed a memory leak in the new, more flexible lsl.reader modules

Fixed a problem with the data ordering in the lsl.writer modules when a high time resolution (<~2 ms) is used

Fixed a bug in the DR spectrometer reader which incorrectly mapped tuning 2, Stokes I for IQUV-mode observations

Fixed a bug in the new measurement set writer

Added multiple IF support to the FITS IDI writer and reader

Added multiple IF/spectral window support to the CASA measurement set writer

Worked on making the lsl.writer.fitsidi and lsl.writer.measurementset modules more robust

Fixed a bugs in the VDIF reader and writer

Fixed a few bugs in the scripts that ship with LSL

Added unittest2 as an extra dependency for Python 2.6

Version 1.2.1¶

Added a new lsl.common.color module to help bring color to ANSI terminals

Small fix to lsl.imaging.utils.plotGriddedImage() to get the image scale correct for non-all-sky images

Finished moving imageIDI.py over to using the lsl.imaging modules

Changed the default FFT length in correlateTBN.py to 16 channels

Fixed a bug in lsl.common.sdf/sdfADP that caused parseSDF() to crash on SDFs generated by MCS when beam delays/gains were specified

Updated lsl.common.sdfADP to allow two beams at LWA-SV

Cleaned up a few messages in lsl.sim.vis and lsl.reader.ldp so that they use the warnings module

Made problems in lsl.statistics.robust raise ValueErrors if a problem is encountered

Added functions to lsl.common.adp to calculate the magnitude response of the TBN and DRX filters

Small fix to lsl.common.metabundle(ADP).getSessionMetaData() to make it more robust

Updated the lsl.skymap.SkyMapLFSM module to the 2018 April 23 version of the model

Added support for the UQR global ionospheric model to the lsl.misc.ionosphere module

Updated the lsl.reader.cor module to support what ADP at LWA-SV is currently capable of generating

Added OVRO-LWA as a valid station for a few of the LSL scripts that do not depend on detailed configuration information

Fixed a bug in lsl.common.metabundle*.getSessionMetaData() when parsing metadata from failed observations

Various performance enhancements to the C extentions in lsl.correlator

Updated the various lsl.reader extensions to use the read() method of the filehandle to make them more flexible

Improved support for TBF in the lsl.reader.ldp module

Added a writeto() method to lsl.common.sdf/sdfADP.Project to make it easier to write an SDF to a file

Fixed a bug in the PyFFTW usage in lsl.correlator.filterbank and fixed the output scaling

Added a new lsl.version.get_fingerprint() function to help keep track of local changes made to the LSL installation

Added support for writing correlated data to a CASA measurement set

Added ARX filter response measurements for Sevilleta

Version 1.2.0¶

Added a new lsl.common.adp module to help describe ADP

Added support for MCS working with ADP-based stations

Added support for SDFs for ADP-based stations

Addes support for metadata handling for ADP-based stations

Added support for ADP TBF data

Added support for ADP COR data

Added support for complex antenna response to lsl.sim.nec_util.NECPattern

Dropped support for block reads in lsl.reader.drx and lsl.reader.tbn

Added a new interface attribute to lsl.common.stations.LWAStationBase instances

Added support for auto-copy to the LWAUCF in the lsl.common.sdf and lsl.common.sdfADP modules

Added a function to lsl.common.stations, getFullStations(), to return a list of full stations

General code clean-up using pylint

Fixed various bugs found in pylint in seldom-used routines

Moved the C extensions over to version 1.7 of the Numpy C API

Added a new OMP_SCHEDULER macro the the various C extensions to help control how OpenMP schedules things

Added more robust error handling inside the C extensions to help make segfaults more rare

Released the GIL inside the various computing C extensions and some of the LWA file format readers

Added a backport of the Python3 LRU cache module to help with internal caching

Added a new LSLInterfaces attribute to lsl.common.station.LWAStation instances to help keep track of which station uses which modules

Updated various scripts that ship with LSL to support data from LWA-SV

Updated the lsl.reader.ldp module to issue warnings on timetag errors when ‘ignoreTimeTagErrors’ is set to True

Updated the lsl.skymap module to include the Low Frequnecy Sky Model (LFSM)

Added an option for applying an empirical correction to the dipole power pattern to driftcurve.py and plotAntenna.py

Version 1.1.4¶

Fixed a missing import statement and a couple of bugs in splitTBN.py

Fixed a conjugation problem in the lsl.writer.fitsidi module that caused the image to be transposed in AIPS

Fixed a conjugation problem in the lsl.utils.imaging module that caused images created from FITS-IDI files to be transposed

Fixed a source enumeration problem in the lsl.writer.fitsidi module that caused excessive source IDs

Fixed a bug in lsl.reader.vdif that caused gofast.c not to compile with newer versions of gcc

Fixed several problems when using LSL with Numpy >=1.12

Updated test_geodesy.py to work with the revised EOP parameter files

Fixed a formatting typo in lsl.reader.ldp when getInfo() tries to return an invalid key

Fixed a bug in lsl.reader.buffer that could lead to some invalid frames being added to the buffer

Dropped support for ADP DRX8 in the lsl.reader.buffer module

Dropped support for FreeBSD

Added support for printing to location of sync. errors in the lsl.reader modules

Version 1.1.3.2¶

Applied a fix for the course FIFO phase jumps in the core.c FEngineC2/3 functions.

Version 1.1.3.1¶

Re-fixed a bug in the complex functions in lsl.correlator._spec and lsl.correlator._stokes that caused the negative frequencies in odd-sized FFTs to be unpacked incorrectly

Version 1.1.3¶

Fixed a bug in the complex functions in lsl.correlator._core, lsl.correlator._spec, and lsl.correlator._stokes that caused the negative frequencies in odd-sized FFTs to be unpacked incorrectly

Updated the tai-utc.dat file for the upcoming leap second in December 2016

Changed the Earth orientation parameters data source to the IERS FTP server

Version 1.1.2¶

Fixed a bug in the lsl.reader.ldp.TBWFile class that caused the wrong start time to be returned in some cases

Fixed a missing import statement in tbnSpectra.py that caused the script to fail when a metadata tarball as passed in on the command line

Updated the lsl.writer.fitsidi module to be more efficient

Updated the lsl.writer.uvfits module to be more efficient

Updated the lsl.imaging.utils.CorrelatedMS function to work with MeasurementSets stored inside a tarball

Small change to lsl.correlator.uvUtils.computeUVW to make it faster for large frequency arrays

Added ‘memmap’ and ‘clobber’ keywords to the various lsl.writer modules to expose a consistent interface

Small fix in imageIDI.py to make it work with CASA MeasurementSets

Transitioned to the native C complex type for the various C extensions

Added ‘memmap’ and ‘clobber’ keywords to the various lsl.writer modules to expose a consistent interface

Small fix in imageIDI.py to make it work with CASA MeasurementSets

Transitioned to the native C complex type for the various C extensions

Added better support VDIF files in the lsl.reader.vdif module

Added a ring buffer for VDIF files to the lsl.reader.buffer module

Added support for single tuning beam SDFs

Fixed a couple of bugs that caused FITS IDI files to have invalid uvw coordinates

Added an option to imageIDI.py to show the time in UTC instead of LST

Updated the LWA1 SSMIF to the 7 July 2016 version

Version 1.1.1¶

Fixed a bug in the lsl.statistics.robust.checkfit function

Fixed a few modules that caused problems with automatic recasting in newer versions of NumPy

Cleaned up the lsl.misc.dedispersion.delay() function so that it will work with lists of single frequency values

Small fix to the lsl.imaging.selfCal module to make it more robust when not all antennas are present

Updated the updateLSLSSMIF.py script to use the new LWA1 SSMIF location on the archive

Added new ionosphere model sources to the lsl.misc.ionosphere module

Changed the disk caching to lsl.misc.ionosphere to store only gzipped files

Added options for other model sources to getIonosphericRM.py

Fixed a bug in correlateTBW.py/correlateTBN.py that causes the script to usually write out an Extended IDI file

Fixed a bug in splitSession.py that caused the script to crash

Updated the various FITS-based writers to remove the old PyFITS API that is no longer supported

Version 1.1.0¶

Updated the lsl.imaging.deconv module to include a source-based CLEAN method and a forward-modeling/least squares method

Added support for phase centers other than zenith to the various functions in lsl.imaging.overlay

Added support for determining coordinates for images with phase centers other than zenith to the lsl.imaging.utils module

Added a new image analysis module, lsl.imaging.analysis, that allows one to find point sources in a 2-D image

Added backward compatibility for older metadata tarball formats to the lsl.common.metabundle module (Ticket #61)

Added preliminary support for working with circular polarizations in the correlator (lsl.correlator.fx) and imaging (lsl.imaging.utils) modules

Added an option of imageIDI.py to overlay a topocentric graticle rather than a equatorial one

Added better support for non-linear polarizations to imageIDI.py

Added support for retrieving the file start time in samples to the various lsl.reader.ldp.LDPFileBase sub-classes

Removed the lsl.misc.mathutil.robustmean() function in favor of lsl.statistics.robust.mean()

Added a function to the lsl.astro module to help deal with correcting a celestial coordinate for nutation

Added support for image weighting and tapering with the new lsl.imaging.utils.ImgWPlus class

Switched lsl.imaging.utils.buildGriddedImage() over to using the new ImgWPlus class

Added a new RadioEarthSatellite class to lsl.sim.vis help with simulating satellites that may be transmitting within the observing band

Added the lsl.misc.ionosphere module to help with computing the dispersion and rotation measure of the ionosphere

Added a new script, getIonosphericRM.py, that uses the lsl.misc.ionosphere module to estimate the rotation measure during an observation

Added a new VDIF reader

Improved the speed of the 4-bit TBW, TBN, and DRX reads through look-up tables

Improved support for UVFITS files written by AIPS

Added multiple integration selection to the various readers in lsl.imaging.utils

Added support for phase centers other than zenith in the FITS-IDI writer

Made the ‘phaseCenter’ keyword in lsl.correlator.fx.FXMaster and lsl.correlator.fx.FXStokes more flexible by allowing other data types

Switched the various CorrelatedData readers in lsl.imaging.util to only using the metadata for building the station information

Version 1.0.3¶

Fixed a bug in the inspectTarball.py script that caused it to crash on TBN/TBW metadata

Added fallbacks to lsl.misc.geodesy to use a backup EOP server if the primary is unreachable

Fixed a bug in imageIDI.py that caused it to crash if a FITS image is not saved

Added a new module, lsl.misc.rfutil, to help with understanding commercial antenna properties

Moved the calculateSEFD() function out of lsl.sim.vis and into lsl.misc.rfutil

Changed the meaning of the ‘ForceGaussian’ keyword in lsl.sim.vis.buildSimArray to contain the Gaussian full widths at half maximum in degrees

Added Boltzmann’s constant to lsl.common.constants

Added a ‘color’ keyword to the various functions in lsl.imaging.overlay to change the color of the overlay

Added a ‘marker’ keyword to the lsl.imaging.overlay.source() to change symbol of the source overlay

Added a function to lsl.statistics.robust to help estimate the mode of a data set using the half-sample method

Fixed the __all__ declaration in the lsl.writer.sdfits module

Fixed a bug in the lsl.common.progress.ProgressBarPlus class that caused the time estimates not to get updated when using __iadd__

Fixed a bug in the splitSession.py script that caused it to die on truncated data files (Ticket #60)

Fixed a bug in imageIDI.py that assumed that ‘xx’ was always present in the data

Fixed a bug in the lsl.reader.ldp.DRXFile class that caused the tuning frequencies to be reported wrong by getInfo()

Changed how the lsl.reader.ldp.*.readFrame() functions interact with the time tag checker

Fixed the ranging of phases coming out of the lsl.imaging.selfCal module

Added ‘axis’ and ‘dtype’ keywords to the various statistical functions in lsl.statistics.robust and lsl.misc.mathutil to make the functions more compatible with their numpy counterparts

Added ‘boundary’ and ‘fill_value’ keyword to the lsl.misc.dedispersion.incoherent() function to make it clear how the time boundary is handled

Added options to the imageIDI.py script to make it easy to change which dipoles are used for imaging

Added an option to the correlateTBW/correlateTBN scripts to correlate all dipoles, regardless of status in the SSMIF

Fixed a bug in lsl.imaging.utils.CorrelatedData() that makes the IOErrors more transparent

Added a deprecation warning to the lsl.misc.mathutil.robustmean() function since it will be removed in 1.1.x

Added options to the splitSession script to give better control over the output

Added options to the possm script that makes it behave more like imageIDI

Fixed a problem in the lsl.imaging.deconv module when computing the positions of RadioFixedBody instances

Fixed a bug in the lsl.sim.vis.buildSimArray() function that caused the simulation array date not to match the input if ‘jd=None’

Fixed a bug in the lsl.sim.vis.buildSimData() function that caused the wrong antenna gain pattern to be applied

Fixed a bug in the lsl.imaging.utils module that causes the AntennaArray instances returned by the CorrelatedData readers to be out-of-order in some cases

Cleaned up the DR spectrometer reader so that file alignment is not lost when a syncError is raised

Version 1.0.2¶

Added documentation for LDP to the Sphinx build system

Added a call to close() for the data dictionary used in lsl.sim.vis.buildSimArray

Fixed a version number regression in lsl.correlator.fx

Added a call to close() for the data dictionary used in lsl.skymap.SkyMapGSM

Version 1.0.1¶

Added an option to updateLSLSSMIF.py to update the LWA1 SSMIF using a local file

Fixed a build problem on OS X with Python 2.7

Added support for using PyFFTW in the lsl.misc.dedispersion module

Added support for using PyFFTW in the lsl.correlator.filterbank module

Fixed a sign problem in the rewritten lsl.skymap.ProjectedSky class that caused the sky to invert in azimuth

Added support for FFTW wisdom

Switched the various C extensions over to used the floating point version of FFTW

Changed the name of the lsl.stations.LWAStation method for finding the distance and direction to another point on surface of the Earth from ‘getPointingAndDirection’ to ‘getPointingAndDistance’

Updated the lsl.misc.gaussparams function to imporve the 2-D fits

Removed the requirement for a BANDPASS table in the lsl.imaging.utils.CorrelatedDataIDI class

Reworked the lsl.reader.ldp module to provide a more object oriented way to access data files

Fixed a packing bug in the lsl.sim.drx.frame2frame function

Fixed a bug in lsl.imaging.utils.CorrelatedDataUV that cause getDataSet to always return all data

Fixed the baseline ordering in FITS IDI files that use the stand number mapper

Updated the FITS IDI reader to use the UVFITS scheme for determining baseline sets

Major overhaul of the lsl.sim.vis module to use a new C-based simulation extension instead of AIPY

Fixed a bug in lsl.correlator.fx that caused the number of overlapped FFTs to be calculated incorrectly

Fixed a bug in lsl.correlator.fx.FXMaster/FXStokes that caused the last FFT window to be excluded from the integration

Removed the lsl.correlator.fx.SpecMasterP function

Updated the lsl.imaging.utils module to better deal with sparse FITS IDI/UVFITS files

Added support for the new MCS beam-dipole mode via the SDF keyword OBS_BDM

Various fixes to the lsl.imaging.deconv module

Added a plotting helper function to lsl.imaging.utils

Added a new overlay module for images called lsl.imaging.overlay

Fixed several bugs in lsl.sim.vis and lsl.imaging.utils related to single-channel data sets

Added an option to export the images created to imageIDI.py to a FITS image file

Small bugfix to the lsl.writer.tsfits module with regards to processing DRX frames

Cleaned up the setup.py script to uses NumPy’s internal facilities to identify ATLAS

Updated the list of dependencies to include pytz

Added the ‘iauConvention’ keyword to the lsl.misc.beamformer.circularize() function

Added a few new convenience functions to the lsl.reader.drspec module

Added ‘lwavl’ as an alias to ‘lwa1’ in the lsl.common.stations module

Added methods to return the response curves of the FEE and Cable to the lsl.common.stations module

Fixed a bug in lsl.imaging.utils.CorrelatedData() that caused IOErrors to be get masked

Version 1.0.0¶

Added in LWA Development Primitives module (lsl.reader.ldp)

Added a function to lsl.misc.beamformer to convert X and Y linear pols. to circular L and R pols

Removed the lsl.correlator.visUtils module since it isn’t used by any other modules or scripts

Switched the lsl.correlator modules over to returned all ‘LFFT’ channels

Replaced the Fermi first point source catalog with the 2-year catalog

Dropped libnova in favor of PyEphem for the backend to the lsl.astro module

Modified skymap.ProjectedSkyMap to not rely on the lsl.astro_array module

Removed the lsl.astro_array module

Removed the lsl.libnova module and the associated swig file

Updated the documentation to reflect the reduced dependencies

Update lsl.common.stations.LWAStation to be a sub-class to ephem.Observer

Added a function to lsl.common.stations.Antenna to access information about the impedence mis-match

Added an option to the various response functions in lsl.common.stations to return values in dB

Switch the information/SSMIF for the north arm site to lwana instead of lwa2 to avoid confusion with the SV site

Renamed the lsl.common.stations.LWAStation.getECEFTransform() function to getECITransform() to reflect what is really happening

Added a function to lsl.imaging.utils to make it easy to re-phase a data dictionary to a new pointing center

Added new functions to the LWAStation class to deal with direction and distance to other stations/points on the Earth

Generalized the computeUVW() and computeUVTrack() functions

Added a disk-based cache to the lsl.misc.geodesy module to help keep network traffic down

Added support for reading and writing UVFITS files

Added support for reading CASA measurement sets via pyrap

Added a function to rephase a visibility data dictionary to a new pointing center

Improved the visibility simulation speed in lsl.sim.vis

Added try…except blocks to lsl.common.metabundle to clean up after failed functions

Added append() functions to Project and Session in lsl.common.sdf to make it easier to add sessions and observations

Added a setSpectrometerMetatag() function to lsl.common.sdf.Session to make setting the metatag easier

lsl.common.sdf.Project.render() now calls update() to make sure everything is up-to-date before rendering

Added ‘verbose’ keywords to lsl.imaging.utils.buildGriddedImage() and the lsl.imaging.selfCal functions

Added a ASCII busy indicator for long running tasks

Added a script to make it easier to update the internal LWA1 SSMIF used by LSL

Version 0.6.6¶

Fixed a problem with older NumPy installs not having a close() function

Fixed a bug in the splitTBN.py and splitDRX.py scripts when a ‘count’ is not provided

Fixed the try…except blocks in lsl.statistics.kurtosis.getLimits() to catch the appropriate error

Improved the end buffering the in lsl.misc.dedispersion.coherent() function

Updated the LWA1 SSMIF to the 131031 version

Fixed a typo in the help for correlateTBN.py

Version 0.6.5¶

Fixed the time remaining computation in lsl.common.progress.ProgressBarPlus

Fixed a bug in imageIDI.py that caused the LST not to update on subsequent integrations

Added in a call to close() after numpy.load() is used

Updated the setup.py script to help deal with clang/OpenMP on OSX

Updated the lsl.common.metabundle module to deal with the new _metadata.txt file format

Added a method to read in MCS MIB files in the GDBM format

Added new functions to lsl.common.metabundle to retrieve the ASP configuration from a new metadata tarball

Version 0.6.4¶

Cleaned up the coherent part of the dedispersion module

Added a time estimating progress bar to lsl.common.progress

Fixed the data scaling in the SoftwareDP _processStreamFilter() function

Fixed the integration time stored in the FITS IDI files generated by correlateTBW.py

Added validation for the DR spectrometer channels/integration count/mode in an SDF

Fixed a couple of typos in the DR spectrometer reader that mixed the I-only and Q-only output modes

Fixed the ‘fills’ normalization in the DR spectrometer reader for the YX-only, YY-only, XX/YY, and XX/XY/YX/YY modes

Fixed the axis order in the SDFITS writer

Version 0.6.3¶

Fixed a typo. in lsl.imaing.utils.pruneBaselineRange() function

Added normalization by the transform length to the lsl.reader._gofast module

Added back in the “import lsl; lsl.test()” fixture

Updated the plotUVcoverage.py script to work with all 260 stands

Fixed the data volume computation for lsl.common.sdf.Stepped observations

Updated the imageIDI.py script to work with either correlated TBW or TBN files

Reorganized the scripts to better handle metadata and removed the IOC scripts

Changed the default values of SESSION_LOG_SCH and SESSION_LOG_EXE in lsl.common.sdf to False

Fixed the lsl.common.sdf.Stepped class so that the step lists of independent

Added the pointing correction keywords to the binary SSMIF reader

Fixed a bug in the calculation of cable delays

Fixed the order of the optional SESSION_* keywords in the SDF renderer

Updated the SDF parser to better work with SDFs that contain custom beamforming

Added convenience functions to the lsl.common.mcs module to help pack delays and gains for custom beamforming SDFs

Updated the included LWA1 SSMIF to the March 10, 2013 version

Added support for phase offsets to the lsl.sim.vis.scaleData() function

Improved the lsl.imaging.selfCal module by added in new methods

Fixed the decimation values for the TBN and DRX CIC filters

Version 0.6.2¶

Fixed a bug in splitDRX.py that caused the script to die if an –offset was passed in

Fixed a bug in lsl.common.mcs that caused binary packed files to be read in incorrectly on 32-bit installs

Fixed a bug in lsl.misc.beamformer that caused the beam simulators to fail when running in single-thread mode

Added frequency keywords to the integer delay-and-sum beamformer functions

Fixed a problem with the beam power pattern measured by lsl.misc.beamformer.intBeamShape

Overhaul of the lsl.common.sdf module to address Ticket #40 (OBS_DRX_GAIN problem) and to improve the render

Removed jinja2 as a dependency

Fixed a bug in lsl.common.sdf dealing with parsing LST times

Added the inspectTarball.py script

Added an option to the lsl.imaging.utils.CorrelatedData class to only return baselines in a certain uv range

Updated the LWA1 SSMIF to the 2013/1/23 version to include the LEDA outriggers

Version 0.6.1¶

Added support for DROS metatags in the SESSION_SPC SDF keyword

Version 0.6.0¶

Removed the correlator.fx.calcSpectra()/calcSpectrum() functions

Removed the lsl.common.warns module

Removed the LWAFS-specific modules since they are not needed for the new DROS v2

Updated the DR spectrometer reader (lsl.reader.drpsec) for the new DROS v2

Version 0.5.5¶

Added in the pointing correction rotation code to lsl.common.mcs as applyPointingCorrecton()

Made the visibility simulations consistent with the output of lsl.correlator.fx.FXMaster()

Added a new lsl.writer.fitsidi.ExtendedIDI class to deal with more than 255 antennas

Updated lsl.imaging.utils to deal with the new ExtendedIDI class

Added in the self-calibration routines to lsl.imaging.selfCal

Updated the LWA1 and LWA2 SSMIFs

Fixed the observatory/instrument specific header values in lsl.writer.fitsidi so that they reflect the different sites

Updated lsl.misc.dedispersion.coherent() to deal with the padding better

Version 0.5.4¶

Switched over to transparent compression in the lsl.common.metabundle functions

Added support for ‘/’ seperated YYYY/MM/DD in lsl.common.sdf.parseTimeString()

Removed the ‘return’ values from the _gofast module import call

Various cleanups in the C extentions to remove compile time warnings

Tweaked the splitDRX.py script to be more robust

Added support for libnova version 0.15.0

Improved support for STEPPED observations in lsl.common.sdf

Made the TBW read-out duration calculation consistent with the current version of MCS

Changed the allowed TBN tuning from 10 to 88 MHz to 5 to 93 MHz

Tweaked lsl.common.beamformer.phaseAndSum() to automatically exclude bad stands

Removed a testing block from lsl.common.beamformer.intDelayAndSum() which only sums the first 20 antennas

Version 0.5.3¶

Changed the DROS spectrometer reader to match the new format

Fixed the documentation for the various correlator.fx spectra functions

Updated the sphinx documentation to address Ticket #25

Added the session splitting script to IOC to address Ticket #24

Changed lsl.common.mcs.mjdmpm2datetime() to return naive datetime instances (Ticket #26)

Fixed a bug in lsl.common.sdf.Project that causes some observation non-overlaps to be reported as overlaps

Fixed a bug in the setup.py script that caused it to crash on systems without pkg-config installed

Modified splitDRX.py to cope with DRX data that begins with frames that list a decimation of zero

Added support for parsing the OBS_DRX_GAIN and OBS_TBN_GAIN keywords in the SDF parser

Cleaned up drxSpectra.py to better deal with files that have a tuning missing at the beginning or where the sample rate changes at the beginning of the file

Added a module to lsl.misc to generate autostereograms from 2-D NumPy arrays

Fixed a bug in lsl.misc.geodesy related to an exception that is thrown when the URL cannot be reached

Added support for parsing LST times at LWA-1 in lsl.common.sdf.parseTimeString()

Version 0.5.2¶

Fixed a bug in gatherDebugging.py that caused the script to crash on missing modules

Fixed a bug in FEnginep[RC][23] that caused segmentation faults in Python 2.7

Made the module path finder a little more robust

Updated the LWA1 SSMIF to the May 16, 2012 version to include the latest antenna status codes

Added a beamformer to lsl.common.dp.SoftwareDP

Changed lsl.common.dp.SoftwareDP.apply() to lsl.commondp.SoftwareDP.applyFilter()

Fixed multi-threading in the lsl.common.dp.SoftwareDP class

Added a clock offset parameter to the cable model (lsl.common.stations.Cable)

Cleaned up the correlateTBW.py scripts

Fixed a bug in the correlator integer sample delays

Fixed bugs in the lsl.misc.beamformer module related to delays

Fixed the URL used by lsl.misc.geodesy.__loadHistoric1992()

Added support for FreeBSD

Added datetime <-> MJD/MPM conversion functions to lsl.common.mcs

Converted lsl.common.progress.ProgressBar to a rotating progress bar

Version 0.5.1¶

Added jinja2 to the list of install dependencies

Fixed the segfault associated with the DR spectrometer reader

Cleaned up how splitDRX.py offsets in a file

Removed splitTBW.py since it is no longer needed

Fixed a few bugs in the SDF parser dealing the logging keywords

Modified lsl.common.metabundle.getSessionDefinition to use the SDF in the tarball rather than generate it from the session and observation specification files

Made drxSpectra.py robust against DRX frames with decimation of zero

Made the SDF parser more robust against single word names

Version 0.5.0¶

Worked on adding better polarization support to correlator.fx and correlator.uvUtils

Updated the correlateTBN script to make full polarization support possible

Added a crude deconvolution routine that should work with the AIPY ImgW images

Worked on adding in support for binary packed SSMIF files in lsl.common.stations

Worked on adding in support for binary packed SDM files via a new lsl.common.sdm module

Worked on adding in support for the various MCS meta-data tarball file formats

Moved the SDF module out of SessionSchedules and into lsl.common

Added functions to generate the TBN and DRX filter magnitude response

Added versions of the spectra plotters, the correlations, and the stand plotters that use MCS meta-data bundles

Added a basic SSMIF file for the north arm site (LWA-2)

Added a preliminary module for incoherent dedispersion lsl.misc.dedispersion

Added support for spectral kurtosis via lsl.statistics.kurtosis

Updated the dependency list

Cleaned up the TBN ring buffer using deques and OrderedDicts

Added support for reading the TBN tuning word/frequency and gain from a TBN frame

Added support for reading the DRX tuning word/frequency from a DRX frame

Added support for stepped SDF files that specify the delays and gains to use

Added support for ARX board/channel responses via a new common.stations.ARX class

Removed the misc.beamformer.fftDelayAndSum functions in favor of phase-and-sum beamforming

Fixed a problem on some platforms with Numpy/LSL version determination in gatherDebugging.py

Cleared the post-interpreter multiprocessing/logging errors during ‘test’

Added support for the DR spectrometer output data format

Added support for computing Stokes parameters from timeseries data

Removed deprecated and unused functions from lsl.correlator.fx

Added support for computing Stokes parameters in the FX correlator and fixed the FITS IDI writer to save the data

Removed S60 reader/simulator

Reworked the SDFITS writer to make it more like the FITS IDI writer

Version 0.4.5¶

Tweaked how the averaging in drxSpectra and tbnSpectra is performed

Upgraded the lsl.reader.drsu module to work with larger file count LWAFS

Added a ls-style script, lsDRSU.py, to list the contents of a DRSU

Added a glob-style function to the DRSU module

Added an array-geometry correction to the correlator to phase up on zenith

Updated the dependency list

Added ARX channel mapping information to lsl.common.stations.Antenna instances

Added a new versioning system to make it easier to access the LSL version in python

Fixed a mapping problem in plotStands.py that mapped by digitizer, not stand

Added a gatherDebugging.py script alongside setup.py to help with debugging and installation problems

Moved gatherDebugging.py to the script directory to have it installed with LSL

Added ‘documentation support’ for accessing the central frequency of a DRX frame

Fixed a RPD_DD mapping problem in lsl.common.stations.parseSSMIF()

Fixed a DP1_SLOT parsing problem in lsl.common.stations.parseSSMIF()

Updated LWA-1 SSMIF to 12/26/2011 to include calibration information

Added the June 30, 2012 leap second into the TAI-UTC file

Fixed a problem in cpDRSU.py with the verbose output

Cleaned up the ‘sfdisk’ calls with the DRSU direct-access module

Added a BeamAlm class to lsl.sim.vis to help with polarization difference between LWA1 and what is implemented in AIPY

Version 0.4.4.1¶

Fixed the missing cable attenuation parameters in the SSMIF

Version 0.4.4¶

Added an id number attribute to lsl.common.stations.FEE objects

Updated LWA-1 SSMIF to 2011-08-10 version

Added ‘keep’ option to tbnSpectra.py to only display a certain collection of stands

Possibly cleared up a install problem on some systems that prevents testing

Fixed various memory leaks in the readers and the direct DRSU access module

Added ‘documentation support’ for accessing the central frequency of a TBN frame

Added support for variable noise level in the various lsl.sim.dp functions

Worked on improving ATLAS library detection on Redhat-based distributions

Improved detection of potential build problems with the DRSU direct-access extension

Updated the coordinates of stand #148 to be consistent with the revised LWA-1 survey

Fixed the digitizer to board mapping to account for DP2 boards

Fixed a bug simulating visibilities that could include sources below the horizon

Fixed the ‘-i’ option in gsmnpz2map.py

Version 0.4.3¶

Cleaned up the various __init__.py scripts

Fixed a few typos in lsl.correlator.uvUtils

Fixed a typo in the progress bar caused some decrements to increment

Fixed a few typos in lsl.correlator.uvUtils.computeUVTrack

Fixed a typo in the _spec.PPSDC2() function that caused it to die

Fixed several heinous problems in sim.dp.pointSource()

Fixed a bug with indexing in the 4-bit TBW reader

Fixed a few sign errors in correlator _core and uvUtils modules

Fixed a bug in the correlateTBW script related to antenna indexing

Fixed a bug in the FITS IDI writer that caused EOP problems to be fatal

Version 0.4.2¶

Fixed tbwSpectra.py to skip over non-TBW frames at the beginning of a TBW file

Fixed the common.stations.geo2ecef() conversion function (Ticket #16)

Fixed the correlator.fx.FXMaster() function (Ticket #18)

Fixed a few type conversion problems in correlator._core (core.c) introduced with the new data types

Fixed a frequency units conversion in tbnSpectra.py

Improved polarization support in the FITS IDI writer

Fixed a sign error in the fractional delay correction of the correlator F engine

Improved the speed of the X Engine

Fixed a azimuth definition problem in astro_array.c

Updated the included SSMIF to the 5/18/2011 version

Updated the correlateTBN script to make computing XX and YY products easier

Added support for different cable attenuation models supported in MCS0031, v5

Added support for the old 20-stand prototype system through lsl.common.stations.prototypeSystem

Updated the correlateTBW script to make computing XX and YY products easier

Updated SSMIF with new stretch and cable gain coefficients

Added support for time-domain blanking via the ‘ClipLevel’ keyword to various _spec and _core routines

Version 0.4.1¶

Fixed a problem with the C readers that manifests itself on 32-bit platforms

Modified sphinx to be more independent about version numbers and release notes

Added additional PyDict checks to the _gofast module

Modified lsl.sim.drx to zero the frame and seconds counts to make the DRX frames ICD compliant

Fixed a small bug in lsl.sim.tbw/tbn/drx that caused the seconds counts to be wrong

Version 0.4.0¶

Added new robust statistical methods

Added Global Sky Model models to skymap

Added new smoothing and fitting functions to misc.mathutil

Added a progress bar for use with long-running applications

Added in new LWA-1 dipole NEC models

Re-worked the plotAntenna.py script to use the pre-computed dipole response fits

Added support for EXCITATION keywords in misc.nec_util

Added new gofast readers for TBW, TBN, and DRX

Added better polyphase filter support

Fixed initialization problems the various lsl.reader Frame objects

Fixed the TBN ring buffer

Added support for simulating point sources in TBW and TBN data

Moved the tests directory out of lsl proper

Added new offset/average options to drxSpectra and tbnSpectra

Added new DRSU direct access module for Linux system (experimental)

Added documentation for the various C extensions

Updated the dependencies list to capture everything needed for the extensions

Version 0.3.4.2¶

Fixed a couple of typos. in the correlator scripts

Added more colors to tbwSpectra.py so that all 20 inputs can be plotted

Fixed problems with DRX frame attributes

Fixed filter code problems in the DRX writer

Fixed typo in URL for libnova

Added a brief tutorial for DRX data

Fixed a problem determining if a TBW chunk has enough samples to FFT

Version 0.3.4.1¶

Fixed various documentation problems

Version 0.3.4¶

Added in the new cable attenuation model

Re-wrote the TBW reader so that is it ~40% faster

Removed unnecessary “import” statements in the TBW, TBN, and DRX readers

Fixed slow frame creation by sim.dp on 64-bit systems

Added in the new C-based correlator

Major re-organization of correlator.fx with regards to windowing functions

Switched from ‘processing’ to ‘multiprocessing’

Added the possm.py script for each FITS IDI examination

Fixed tbwSpectra.py and tbnSpectra.py to accommodated the windowing change

Added drxSpectra.py

Fixed various problems with the DP data simulator

Added in option to cable losses in tbwSpectra.py

Fixed a problem in the sim.vis.Antenna class function get_beam_shape

Added in a correlator script for TBW

Added new beam models for use with AIPY based on SLC0015

Version 0.3.3¶

Fixed stand indexing error in uvUtils.cableAttenuation

Fixed Mac OS X tbnSpectra.py plotting problem (Ticket #3)

Spectra generated by tbwSpectra.py and tbnSpectra.py now agree with IDA v0.1

Fixed problems with the frame comparison attributes

Re-wrote the TBN reader so that it is ~20% faster

Fixed syntax errors in misc.difxconfig

Fixed MemoryError problem for some systems with tests.test_vdiff (Ticket #7)

Fixed a problem that caused some systems to assume that LSL was zip safe

Added new stand mappings that correct the 3/4 pair swaps

Version 0.3.2¶

Added new “tutorial” style documentation for various parts of LSL

Added scripts tbwSplit.py and tbnSplit.py to split large TBW and TBN files down to more manageable sizes

Version 0.3.1¶

Fixed various typos. in correlator.fx, misc.beamformer, and reader.buffer

Added “close” function to writer.fitsidi

Version 0.3.0¶

New setuptools-based build system

New, improved documentation

Added post-acquisition beam forming module

Added in modules for writing simulated data to the S60, TBW, TBN, and DRX raw data formats

Added a module for simulated basic test signals in TBW, TBN, and DRX data

Moved the lwa_user script ‘astrostatus.py’ into the scripts directory

Fixed the FITS IDI writer

Fixed a couple of bugs dealing with incorrect chunking of data in scripts/tbwSpectra.py and scripts/tbnSpectra.py

Version 0.2.0¶

Added in other modules from the lwa_user library developed by NRL

Version 0.1.0¶

Initial version

lwa_user Modules¶

The lwa_user modules included in LSL are:

lwa_user	lsl
Name	Name	Version
lwa_user.astro	lsl.astro	0.2
lwa_user.catalog	lsl.catalog	0.2
lwa_user.mathutil	lsl.misc.mathutils	0.1
lwa_user.skymap	lsl.skymap	0.2
lwa_user.transform	lsl.transform	0.2

General Utilities¶

Astronomical Utilities¶

New in version 0.2.

Astronomical utility functions and classes based on libnova library.

lsl.astro.B1950_to_J2000(pos)¶

Convert B1950 epoch to J2000 epoch for equatorial coordinates.

Param: pos - object of type equ_posn giving B1950 coordinates

Returns: object of type equ_posn giving J2000 coordinates.

Note

The accuracy of this function is about 0.01 degrees.

lsl.astro.J2000_to_B1950(pos)¶

Convert J2000 epoch to B1950 epoch for equatorial coordinates.

Param: pos - object of type equ_posn giving J2000 coordinates

Returns: object of type equ_posn giving B1950 coordinates.

Note

The accuracy of this function is about 0.01 degrees.

lsl.astro.add_hms(source, dest)¶

Adds time/angle hours, minutes, seconds.

Param: source - Object of type hms represeting angle 1. Param: dest - Object of type hms represeting angle 2.

Returns object of type hms representing sum of angles.

lsl.astro.add_secs_hms(hms, seconds)¶

Add seconds to time/angle hours, minutes, seconds.

Param: hms - Object of type hms representing angle. Param: seconds - Seconds offset (float) to add to angle.

Returns object of type hms representing angle + offset.

class lsl.astro.date(years=2000, months=1, days=1, hours=0, minutes=0, seconds=0.0)¶

Represents UT time in calendar units.

Public members:: years - Date years (integer). months - Date months (integer). days - Date days (integer). hours - Date hours (integer). minutes - Date minutes (integer). seconds - Date seconds (float).

load(dateStr, timeStr)¶

Load date object from formatted strings.

Param: dateStr - A string of format YYYY-MM-DD giving date. Param: timeStr - A string of format HH:MM:SS.S giving time.

to_jd()¶: Convert calendar time to Julian day. Returns UTC time in Julian days (float).

to_zone(gmtoff=None)¶

Convert UTC calendar time to local calendar time.

Param: gmtoff - local seconds offset from UTC (integer -43200 to 43200).: if set to None, the time module offset value is used for current location

Returns object of type zonedate representing local time.

lsl.astro.date_to_zonedate(date, gmtoff)¶

Convert UTC calendar time to local calendar time.

Param: date - A date object representing UTC time. Param: gmtoff - Seconds offset from UTC (integer -43200 to 43200).

Returns object of type zonedate representing local time.

lsl.astro.deg_to_dms(degrees)¶

Convert angles float degrees to degrees, minutes, seconds.

Param: degrees - Angle in degrees (float).

Returns object of type dms representing angle.

lsl.astro.deg_to_hms(degrees)¶

Convert angles float degrees to hours, minutes, seconds.

Param: degrees - Angle in degrees (float).

Returns object of type hms representing angle.

lsl.astro.deg_to_rad(degrees)¶

Convert degres to radians.

Param: degrees - Angle in degrees (float).

Returns angle in radians (float).

lsl.astro.deg_to_sec(degrees)¶

Convert longitude degrees into time seconds.

Param: degrees - longitude (float degrees)

Returns: Seconds (float) offset in time for longitude.

lsl.astro.dir_cos(posn)¶

Get direction cosines from azimuth and zenith angles. This function calculates the cosine values based on the LWA coordinate system: l = unit vector in E direction (azimuth = 90) m = unit vector in N direction (azimuth = 0) n = unit vector in zenith direction (zenith = 0, altitude = 90)

Param: posn - object of type hrz_posn giving local position

Returns a tuple (l,m,n) of float values for the direction cosines.

class lsl.astro.dms(neg=False, degrees=0, minutes=0, seconds=0.0)¶

Represents angles in degrees, minutes, seconds.

Public members:

neg - True if measured west of GM, south of EQ: False if measured east of GM, north of EQ.

degrees - Angle degrees (integer). minutes - Angle minutes (integer). seconds - Angle seconds (float).

to_deg()¶: Convert angles degrees, minutes, seconds to float degrees. Returns angle in degrees (float).

to_hms()¶: Convert angles degrees, minutes seconds to hours, minutes, seconds. Returns: object of type hms representing angle.

lsl.astro.dms_to_deg(dms)¶

Convert angles degrees, minutes, seconds to float degrees.

Param: dms - Object of type dms representing angle.

Returns angle in degrees (float).

lsl.astro.dms_to_rad(dms)¶

Convert angles degrees, minutes, seconds to radians.

Param: dms - Object of type dms representing angle.

Returns angle in radians (float).

class lsl.astro.ecl_posn(lng=0.0, lat=0.0)¶

Represents position as ecliptic longitude and latitude.

Public members:: lng - Position longitude coordinate (float degrees). lat - Position latitude coordinate (float degrees).
Members may also be accessed by subscript:: ecl_posn[0] = lng ecl_posn[1] = lat

format()¶: Return a tuple (lng, lat) where lng is an dms object and lat is a dms object representing longitude and latitude position coordinates.

to_equ(jD)¶

Get equatorial coordinates from ecliptical coordinates for a given time.

Param: jD - UTC Julian day (float).

Returns object of type equ_posn representing equatorial position.

class lsl.astro.equ_posn(ra=0.0, dec=0.0)¶

Represents equatoral/celestial position coordinates.

Public members:: ra - Position right ascension angle (float degrees). dec - Position declination angle (float degrees).
Members may also be accessed by subscript:: equ_posn[0] = ra equ_posn[1] = dec

angular_separation(posn)¶

Get angular separation from equatorial position.

Param: posn - Object of type equ_posn representing body 2 position.

Returns angular separation in degrees (float).

format()¶: Return a tuple (ra, dec) where ra is an hms object and dec is a dms object representing ra and dec position coordinates.

precess(jD)¶

Get position of celestial object accounting for precession. The equatorial coordinates should be for the J2000 epoch.

Param: jD - UTC Julian day (float) to measure position.

Returns: Adjusted equatorial position of object as type equ_posn.

to_ecl(jD)¶

Get ecliptical coordinates from equatorial coordinates.

Param: jD - UTC Julian day (float).

Returns object of type lnlat_posn representing eclipitcal position.

to_gal(jD)¶

Get J2000 galactic coordinates from apparent equatorial coordinates.

Param: jD - UTC Julian day to get position.

Returns object of type gal_posn representing object’s galactic position.

to_hrz(observer, jD)¶

Get local horizontal coordinates from equatorial/celestial coordinates.

Param: observer - Object of type lnlat_posn representing observer position. Param: jD - UTC Julian day (float).

Returns object of type hrz_posn representing local position.

class lsl.astro.gal_posn(l=0.0, b=0.0)¶

Represents galactic position coordinates.

Public members:: l - Position longitude angle (float degrees). b - Position latitude angle (float degrees).
Members may also be accessed by subscript:: gal_posn[0] = l gal_posn[1] = b

format()¶: Return a tuple (lng, lat) where lng is an dms object and lat is a dms object representing galactic longitude and latitude position coordinates.

to_equ(jD)¶

Get apparent equatorial coordinates from J2000 galactic coordinates.

Param: jD - UTC Julian day to get position.

Returns object of type equ_posn representing object’s apparent equatorial position.

class lsl.astro.geo_posn(lng=0.0, lat=0.0, elv=0.0)¶

Class to represent geographical position in terms of longitude, lattitude, and elevation. This is a set of geodetic coordinates based on the WGS84 model.

Public members:: lng - longitude (float) lat - latitude (float) elv - elevation (float)
Members may also be accessed by subscript:: geo_posn[0] = lng geo_posn[1] = lat geo_posn[2] = elv

lsl.astro.get_angular_separation(posn1, posn2)¶

Get angular separation from equatorial positions.

Param: posn1 - Object of type equ_posn representing body 1 position. Param: posn2 - Object of type equ_posn representing body 2 position.

Returns angular separation in degrees (float).

lsl.astro.get_apparent_posn(mean_position, jD, proper_motion=None)¶

Get apparent position of celestial object accounting for precession, nutation, aberration, and optionally proper motion.

Param: mean_position - J2000 equatorial mean position of object as type: equ_posn.

Param: jD - UTC Julian day (float) to measure position. Param: proper_motion - object of type equ_posn giving object’s proper motion

(optional).

Returns: Apparent equatorial position of object as type equ_posn.

lsl.astro.get_apparent_sidereal_time(jD)¶

Get apparent sidereal time from Julian day.

Param: jD - UTC Julian day (float).

Returns GM apparent sidereal time (float hours).

From: http://aa.usno.navy.mil/faq/docs/GAST.php

lsl.astro.get_date(jD)¶

Convert Julian day to calendar time.

Param: jD - UTC time in Julian days (float).

Returns object of type date representing UTC time.

lsl.astro.get_date_from_sys()¶

Gets calendar time from system clock.

Returns object of type date representing UTC time.

lsl.astro.get_day_of_week(date)¶

Gets day of week from calendar time.

Param: date - Object of type date representing UTC time.

Returns day of week (0 = Sunday, 6 = Saturday).

lsl.astro.get_ecl_from_equ(target, jD)¶

Get ecliptical coordinates from equatorial coordinates for a given time.

Param: target - Object of type equ_posn representing equatorial position. Param: jD - UTC Julian day (float).

Returns object of type ecl_posn representing ecliptic position.

lsl.astro.get_ecl_from_rect(rect)¶

Get ecliptical coordinates from rectangular coordinates.

Param: rect - Object of type rect_posn representing position.

Returns object of type lnlat_posn representing ecliptical position.

lsl.astro.get_equ2000_from_gal(target)¶

Get J2000 equatorial coordinates from galactic coordinates.

Param: target - Object of type gal_posn representing galactic position.

Returns object of type equ_posn representing J2000 equatorial position.

lsl.astro.get_equ_aber(mean_position, jD)¶

Get position of celestial object accounting for aberration.

Param: mean_position - J2000 equatorial mean position of object as type: equ_posn.

Param: jD - UTC Julian day (float) to measure aberration.

Returns: Adjusted equatorial position of object as type equ_posn.

Based on the libnova ln_get_equ_aber() function.

lsl.astro.get_equ_from_ecl(target, jD)¶

Get equatorial coordinates from ecliptical coordinates for a given time.

Param: target - Object of type lnlat_posn representing ecliptic position. Param: jD - UTC Julian day (float).

Returns object of type equ_posn representing equatorial position.

lsl.astro.get_equ_from_gal(target)¶

Get B1950 equatorial coordinates from galactic coordinates.

Param: target - Object of type gal_posn representing galactic position.

Returns object of type equ_posn representing B1950 equatorial position.

lsl.astro.get_equ_from_hrz(target, observer, jD)¶

Get equatorial/celestial coordinates from local horizontal coordinates.

Param: target - Object of type hrz_posn representing horizontal position. Param: observer - Object of type lnlat_posn representing observer position. Param: jD - UTC Julian day (float).

Returns object of type equ_posn representing equatorial position.

lsl.astro.get_equ_from_rect(posn)¶

Transform rectangular coordinates to equatorial coordinates.

Param: posn - Object of type rect_posn giving position.

Returns: Object of type equ_posn giving equatorial coordinates.

lsl.astro.get_equ_nut(position, jD)¶

Get the position of a celesital object accounting for nutation.

Param: mean_position - Equatorial position of object as type: equ_posn.

Param: jD - UTC Julian day (float) to measure nutation.

Returns: Adjusted equatorial position of object as type equ_posn.

Based on the AstroIDL co_nutate.pro procedure

lsl.astro.get_equ_pm(mean_position, proper_motion, jD)¶

Adjusts equatorial position of a stellar object accouting for proper motion.

Param: mean_position - J2000 equatorial mean position of object as type equ_posn. Param: proper_motion - Object of type equ_posn giving object’s proper motion

(units are deg/year).

Param: jD - UTC Julian day (float) to measure position.

Returns: Adjusted equatorial position of object as type equ_posn.

Based on pm.f, dcs2c.f, and dcc2s.f from SLALIB.

lsl.astro.get_equ_prec(mean_position, jD)¶

Get position of celestial object accounting for precession. Only works for converting to and from J2000 epoch.

Param: mean_position - J2000 equatorial mean position of object as type equ_posn. Param: jD - UTC Julian day (float) to measure position.

Returns: Adjusted equatorial position of object as type equ_posn.

lsl.astro.get_equ_prec2(mean_position, fromJD, toJD)¶

Get position of celestial object accounting for precession.

Param: mean_position - equatorial first position of object as type equ_posn. Param: fromJD - UTC Julian day (float) of first time. Param: toJD - UTC Julian day (float) of second time.

Returns: Equatorial position of object as type equ_posn converted from: time 1 to time 2.

lsl.astro.get_gal_from_equ(target)¶

Get galactic coordinates from B1950 equatorial coordinates.

Param: target - Object of type equ_posn representing B1950 equatorial: position.

Returns object of type gal_posn representing galactic position.

lsl.astro.get_gal_from_equ2000(target)¶

Get galactic coordinates from J2000 equatorial coordinates.

Param: target - Object of type equ_posn representing J2000 equatorial: position.

Returns object of type gal_posn representing galactic position.

lsl.astro.get_geo_from_rect(posn)¶

Transform ECEF rectangular coordinates to geographical coordinates. Adapoted from “Satellite Orbits”, Montenbruck and Gill 2005, 5.85 - 5.88. Also see gpstk ECEF::asGeodetic() method.

Param: posn - object of type rect_posn giving position.

Returns: object of type geo_posn giving geographical coordinates.

lsl.astro.get_gmtoff()¶: Get local UTC offset based on Python time module and system info.

lsl.astro.get_hrz_from_equ(target, observer, jD)¶

Get local horizontal coordinates from equatorial/celestial coordinates.

Param: target - Object of type equ_posn representing celestial position. Param: observer - Object of type lnlat_posn representing observer position. Param: jD - UTC Julian day (float).

Returns object of type hrz_posn representing local position.

lsl.astro.get_julian_day(date)¶

Convert calendar time to Julian day.

Param: date - Object of type date representing UTC time.

Returns UTC time in Julian days (float).

lsl.astro.get_julian_from_sys()¶: Returns UTC Julian day (float) from system clock.

lsl.astro.get_julian_from_timet(timet)¶

Gets Julian day from Unix time.

Param: timet - Unix timet in seconds (integer)

Returns UTC Julian day (float).

lsl.astro.get_julian_local_date(zonedate)¶

Convert local calendar time to Julian day.

Param: zonedate - Object of type zonedate representing local time.

Returns UTC time in Julian days (float).

lsl.astro.get_jupiter_equ_coords(jD)¶

Get Jupiter’s apparent equatorial coordinates from Julian day. Accounts for aberration and precession, but not nutation.

Param: jD - UTC Julian day (float).

Returns object of type equ_posn representing equatorial position.

lsl.astro.get_jupiter_rst(jD, observer)¶

Get Jupiter’s rise, transit, set times from Julian day.

Param: jD - UTC Julian day (float). Param: observer - Object of type lnlat_posn representing observer position.

Returns Object of type rst_time represeting UTC ephemeris times,: or None if the object is circumpolar.

lsl.astro.get_local_sidereal_time(lng, jD)¶

Get apparent local sidereal time from Julian day.

Param: lng - longitude degrees (float), E = positive, W = negative Param: jD - UTC Julian day (float).

Returns: Local mean sidereal time (float hours).

lsl.astro.get_lunar_equ_coords(jD)¶

Get the Moon’s apparent equatorial coordinates from Julian day. Accounts for aberration and precession, but not nutation.

Param: jD - UTC Julian day (float).

Returns object of type equ_posn representing equatorial position.

lsl.astro.get_lunar_rst(jD, observer)¶

Get the Moon’s rise, transit, set times from Julian day.

Param: jD - UTC Julian day (float). Param: observer - Object of type lnlat_posn representing observer position.

Returns Object of type rst_time represeting UTC ephemeris times,: or None if the object is circumpolar.

lsl.astro.get_mars_equ_coords(jD)¶

Get Mars’ apparent equatorial coordinates from Julian day. Accounts for aberration and precession, but not nutation.

Param: jD - UTC Julian day (float).

Returns object of type equ_posn representing equatorial position.

lsl.astro.get_mars_rst(jD, observer)¶

Get Mars’ rise, transit, set times from Julian day.

Param: jD - UTC Julian day (float). Param: observer - Object of type lnlat_posn representing observer position.

Returns Object of type rst_time represeting UTC ephemeris times,: or None if the object is circumpolar.

lsl.astro.get_mean_sidereal_time(jD)¶

Get mean sidereal time from Julian day.

Param: jD - UTC Julian day (float).

Returns GM mean sidereal time (float hours).

From: http://aa.usno.navy.mil/faq/docs/GAST.php

lsl.astro.get_nutation(jD)¶

Get nutation corrections for a given time.

Param: jD - UTC Julian day (float) to measure nutation.

Returns: Nutation corrections as object of type nutation.

Based on the nutate.pro and co_nutate.pro from the AstroIDL library.

lsl.astro.get_object_rst(jD, observer, target)¶

Get rise, set, and transit times of a celstial object.

Param: jD - UTC Julian day (float) target time. Param: observer - object of type lnlat_posn giving observer position Param: target - object of type equ_posn giving target equatorial position

Returns: Object of type rst_time giving object’s ephemeris UTC times,: or None if the object is circumpolar.

lsl.astro.get_precession(jD1, pos, jD2)¶

Caculate precession of equatorial coordinates from one epoch to another.

Param: jD1 - UTC Julian day of epoch 1. Param: pos - object of type equ_posn giving epoch 1 position Param: jD2 - UTC Julian day of epoch 2.

Returns: object of type equ_posn giving epoch 2 position.

lsl.astro.get_rect_from_equ(posn)¶

Transform equatorial coordinates to rectangular coordinates.

Param: posn - Object of type equ_posn giving position.

Returns: Object of type rect_posn giving rectangular coordinates (normallized to 1).

lsl.astro.get_rect_from_geo(posn)¶

Transform geographical coordinates to ECEF rectangular coordinates. Adopted from “Satellite Orbits”, Montenbruck and Gill 2005, 5.83 - 5.84. Also see gpstk Geodetic::asECEF() method.

Param: posn - object of type geo_posn giving geographical coordinates.

Returns: object of type rect_posn giving ECEF position.

lsl.astro.get_rel_posn_angle(posn1, posn2)¶

Get relative position angle from equatorial positions.

Param: posn1 - Object of type equ_posn representing body 1 position. Param: posn2 - Object of type equ_posn representing body 2 position.

Returns position angle in degrees (float).

Based on dpav.f from SLALIB.

lsl.astro.get_saturn_equ_coords(jD)¶

Get Saturn’s apparent equatorial coordinates from Julian day. Accounts for aberration and precession, but not nutation.

Param: jD - UTC Julian day (float).

Returns object of type equ_posn representing equatorial position.

lsl.astro.get_saturn_rst(jD, observer)¶

Get Saturn’s rise, transit, set times from Julian day.

Param: jD - UTC Julian day (float). Param: observer - Object of type lnlat_posn representing observer position.

Returns Object of type rst_time represeting UTC ephemeris times,: or None if the object is circumpolar.

lsl.astro.get_solar_equ_coords(jD)¶

Get Sun’s apparent equatorial coordinates from Julian day. Accounts for aberration and precession, and nutation.

Param: jD - UTC Julian day (float).

Returns object of type equ_posn representing equatorial position.

lsl.astro.get_solar_rst(jD, observer)¶

Get Sun’s rise, transit, set times from Julian day.

Param: jD - UTC Julian day (float). Param: observer - Object of type lnlat_posn representing observer position.

Returns Object of type rst_time represeting UTC ephemeris times,: or None if the object is circumpolar..

lsl.astro.get_tai_from_sys()¶: Return the current time taken from the system clock as a TAI MJD (float).

lsl.astro.get_timet_from_julian(jD)¶

Gets Unix time from Julian day.

Param: jD - UTC Julian day (float).

Returns Unix timet in seconds (integer).

lsl.astro.get_venus_equ_coords(jD)¶

Get Venus’ apparent equatorial coordinates from Julian day. Accounts for aberration and precession, but not nutation.

Param: jD - UTC Julian day (float).

Returns object of type equ_posn representing equatorial position.

lsl.astro.get_venus_rst(jD, observer)¶

Get Venus’ rise, transit, set times from Julian day.

Param: jD - UTC Julian day (float). Param: observer - Object of type lnlat_posn representing observer position.

Returns Object of type rst_time represeting UTC ephemeris times,: or None if the object is circumpolar.

class lsl.astro.hms(hours=0, minutes=0, seconds=0.0)¶

Represents times/angles in hours, minutes, seconds.

Public members:: hours - Angle/time hours (integer). minutes - Angle/time minutes (integer). seconds - Angle/time seconds (float).

to_deg()¶: Convert angles hours, minutes, seconds to float degrees. Returns angle in degrees (float).

to_dms()¶: Convert angle hours, minutes, seconds to degrees, minutes, seconds. Returns: object of type dms representing angle.

to_sec()¶: Convert angle hours, minutes, seconds to seconds. Returns: time/angle as seconds.

lsl.astro.hms_to_deg(hms)¶

Convert angles hours, minutes, seconds to float degrees.

Param: hms - Object of type hms representing angle.

Returns angle in degrees (float).

lsl.astro.hms_to_rad(hms)¶

Convert angles hours, minutes, seconds to float radians.

Param: hms - Object of type hms representing angle.

Returns angle in radians (float).

lsl.astro.hms_to_sec(hms)¶

Convert hours, minutes, seconds to seconds.

Param: hms - object of type hms representing time/angle.

Returns: Seconds (float) offset of time/angle.

class lsl.astro.hrz_posn(az=0.0, alt=0.0)¶

Represents horizontal local position coordinates. LWA measures azimuth angle clockwise from north to east, with due north equal to 0 degrees. Also, method for using zenith angle instead of altitude angle have been added.

Public members:: az - Position azimuth angle (float degrees). alt - Position altitude angle (float degrees)
Members may also be accessed by subscript:: hrz_posn[0] = az hrz_posn[1] = alt

dir_cos()¶

Get direction cosines from horizontal coordinates.

Returns: A tuple (l,m,n) of float values for the direction cosines.: l = unit vector in E direction (azimuth = 90) m = unit vector in N direction (azimuth = 0) n = unit vector in zenith direction (zenith = 0, altitude = 90)

to_equ(observer, jD)¶

Get equatorial/celestial coordinates from local horizontal coordinates.

Param: observer - Object of type lnlat_posn representing observer position. Param: jD - UTC Julian day (float).

Returns object of type equ_posn representing equatorial position.

zen(value=None)¶: If value is None, returns position zenith angle (float degrees [0, 180]) Otherwise, sets the altitude according to the zenith angle value.

lsl.astro.hrz_to_nswe(pos)¶

Get cardinal/ordinal azimuth direction.

Param: pos - Object of type hrz_posn giving local position.

Returns string giving direction.

lsl.astro.jd_to_mjd(jd)¶

Get modified julian day value from julian day value.

Param: jd - julian day (should be >= 2400000.5)

Returns: Modified julian day.

lsl.astro.jd_to_sec(jD)¶

Convert Julian days into seconds.

Param: jD - Julian days (float).

Returns: Seconds as a float.

lsl.astro.leap_secs(utcJD)¶

Get the number of leap seconds for given UTC time value.

Param: utcJD - The UTC JD time.: This should be greater than 2441317.5 (1972 JAN 1).

Returns: The number of leap seconds (float) for the UTC time.

class lsl.astro.lnlat_posn(lng=0.0, lat=0.0)¶

Represents position coordinates in latitude and longitude. When representing a geographical location, the longitude is negative when measured west of GM and positive is measured east of GM.

Public members:: lng - Position longitude coordinate (float degrees). lat - Position latitude coordinate (float degrees).
Members may also be accessed by subscript:: lnlat_posn[0] = lng lnlat_posn[1] = lat

format()¶: Return a tuple (lng, lat) where lng is an dms object and lat is a dms object representing longitude and latitude position coordinates.

lsl.astro.mjd_to_jd(mjd)¶

Get julian day value from modified julian day value.

Param: mjd - modified julian day (should be >= 0.0)

Returns: Julian day.

class lsl.astro.nutation(longitude=0.0, obliquity=0.0, ecliptic=0.0)¶

Provides nutation information in longitude and obliquity.

Public members:: longitude - Nutation in longitude (float degrees). obliquity - Nutation in ecliptic obliquity (float degrees). ecliptic - Obliquity of the ecliptic (float degrees).

format()¶: Return a tuple (lng, obl, ecl) where lng is an dms object, obl is a dms object, and ecl is a dms object representing nutation in longitude and obliquity, and obliquity of the ecliptic.

lsl.astro.rad_to_deg(radians)¶

Convert radians to degrees.

Param: radians - Angle in radians (float).

Returns angle in degrees (float).

lsl.astro.rad_to_dms(radians)¶

Convert angles float radians to degrees, minutes, seconds.

Param: radians - Angle in radians (float).

Returns object of type dms representing angle.

lsl.astro.rad_to_hms(radians)¶

Convert angles float radians to hours, minutes, seconds.

Param: radians - Angle in radians (float).

Returns object of type hms representing angle.

lsl.astro.range_degrees(degrees)¶

Put angle into range [0, 360].

Param: degrees - large angle (float degrees)

Returns: angle in range (float degrees)

lsl.astro.range_hours(hours)¶: Put an hour time value into the correct range [0.0, 24.0].

class lsl.astro.rect_posn(X=0.0, Y=0.0, Z=0.0)¶

Represents rectangular/Cartesian position coordinates.

Public members:: X - Position X coordinate (float). Y - Position Y coordinate (float). Z - Position Z coordinate (float).
Members may also be accessed by subscript:: rect_posn[0] = X rect_posn[1] = Y rect_posn[2] = Z

class lsl.astro.rst_time(rise=None, set=None, transit=None)¶

Represents ephemeris rist, set, and transit times.

Public members:: rise - Rise time in UTC Julian days (float). set - Set time in UTC Julian days (float). transit - Transit time in UTC Julian days (float).

format()¶: Return a tuple (rise, set, transit) where all three are date objects representing the ephemeris times.

lsl.astro.sec_to_jd(secs)¶

Convert seconds into julian days.

Param: secs - seconds (float)

Returns: Julian days as a float.

lsl.astro.tai_to_tt(taiJD)¶

Get the TT JD time value for a given TAI JD time value.

Param: taiJD - The TAI JD time (float).

Returns: The TT JD value (float).

lsl.astro.tai_to_utc(taiJD)¶

Get the UTC JD time value for a given TAI JD time value.

Param: taiJD - The TAI JD time (float).: This should be greater than 2441317.5 (1972 JAN 1).

Returns: The UTC JD value (float).

lsl.astro.taimjd_to_unix(taiMJD)¶

Get UNIX time value for a given TAI MJDvalue.

Param: taiMJD - The TAI MJD time (float).

Returns: The UNIX time

lsl.astro.taimjd_to_utcjd(taiMJD)¶

Get the UTC JD time value for a given TAI MJD value.

Param: mjdTAI - The TAI MJD time (float).

Returns: The UTC JD value (float).

lsl.astro.tt_to_tai(ttJD)¶

Get the TAI JD time value for a given TT JD time value.

Param: ttJD - The TT JD time (float).

Returns: The TAI JD value (float).

lsl.astro.tt_to_tdb(ttJD)¶

Get the TDB JD time value for a given TT JD time value. Adopted from “Astronomical Almanac Supplement”, Seidelmann 1992, 2.222-1.

Param: ttJD - The TT JD time (float).

Returns: The TDB JD value (float).

lsl.astro.tt_to_utc(ttJD)¶

Get the UTC JD time value for a given TT JD time value.

Param: ttJD - The TT JD time (float).

Returns: The UTC JD value (float).

lsl.astro.unix_to_taimjd(unixTime)¶

Get the TAI MJD time value for a given UNIX time value.

Param: unixTime - the UNIX time (int/float)

Returns: The TAI MJD value.

lsl.astro.unix_to_utcjd(unixTime)¶

Get the UTC JD time value for a given UNIX time value.

Param: unixTime - the UNIX time (int/float)

Returns: The UTC JD value.

lsl.astro.utc_to_tai(utcJD)¶

Get the TAI JD time value for a given UTC JD time value.

Param: utcJD - The UTC JD time (float).: This should be greater than 2441317.5 (1972 JAN 1).

Returns: The TAI JD value (float).

lsl.astro.utc_to_tt(utcJD)¶

Get the TT JD time value for a given UTC JD time value.

Param: utcJD - The UTC JD time (float).

Returns: The TT JD value (float).

lsl.astro.utcjd_to_taimjd(utcJD)¶

Get the TAI MJD time value for a given UTC JD value.

Param: utcJD - The UTC JD time (float).

Returns: The TAI MJD value.

lsl.astro.utcjd_to_unix(utcJD)¶

Get UNIX time value for a given UTC JD value.

Param: utcJD - The UTC JD time (float).

Returns: The UNIX time

class lsl.astro.zonedate(years=2000, months=1, days=1, hours=0, minutes=0, seconds=0.0, gmtoff=0)¶

Represents local time in calendar units.

Public members:: years - Date years (integer). months - Date months (integer). days - Date days (integer). hours - Date hours (integer). minutes - Date minutes (integer). seconds - Date seconds (float). gmtoff - Seconds offset from GM (integer).

to_date()¶: Convert local calendar time to UTC calendar time. Returns object of type date representing UTC time.

to_jd()¶: Convert calendar time to Julian day. Returns UTC time in Julian days (float).

lsl.astro.zonedate_to_date(zonedate)¶

Convert local calendar time to UTC calendar time.

Param: zonedate - Object of type zonedate representing local time.

Returns object of type date representing UTC time.

RFI Identification¶

New in version 0.5.

Module for computing spectral kurtosis both for instantaneous PSDs and spectrometer output. This module also provides functions to estimate the spectral kurtosis limits for a given confidence interval in sigma.

This module is based on:

Nita & Gary (2010, PASP 155, 595)
Nita & Gary (2010, MNRAS 406, L60)

lsl.statistics.kurtosis.get_limits(sigma, M, N=1)¶: Return the limits on the spectral kurtosis value to exclude the specified confidence interval in sigma using a Pearson Type VI distribution (betaprime in scipy.stats world). The return value is a two-element tuple of lower limit, upper limit.

Note

This corresponds to Section 3.1 in Nita & Gary (2010, MNRAS 406, L60)

lsl.statistics.kurtosis.mean(M, N=1)¶: Return the expected mean spectral kurtosis value for M points each composed of N measurements.

lsl.statistics.kurtosis.skew(M, N=1)¶: Return the expected skewness (third central moment) of the spectral kurtosis for M points each composed of N measurements.

lsl.statistics.kurtosis.spectral_fft(x, axis=None)¶: Compute the spectral kurtosis for a set of unaveraged FFT measurements. For a distribution consistent with Gaussian noise, this value should be ~1.

lsl.statistics.kurtosis.spectral_power(x, N=1, axis=None)¶: Compute the spectral kurtosis for a set of power measurements averaged over N FFT windows. For a distribution consistent with Gaussian noise, this value should be ~1.

lsl.statistics.kurtosis.std(M, N=1)¶: Return the expected standard deviation of the spectral kurtosis for M points each composed of N measurements.

lsl.statistics.kurtosis.var(M, N=1)¶: Return the expected variance (second central moment) of the spectral kurtosis for M points each composed of N measurements.

Dedispersion¶

New in version 0.5.

Module for calculating dispersion delay due to an ionized ISM and performing incoherent/coherent dedispersion.

lsl.misc.dedispersion.coherent(t, timeseries, central_freq, sample_rate, dm, taper=False, previous_time=None, previous_data=None, next_time=None, next_data=None, enable_caching=True)¶

Simple coherent dedispersion of complex-valued time-series data at a given central frequency and sample rate. A tapering function can also be applied to the chirp of the form:

$\sqrt{1 + \left(\frac{\Delta f_{MHz}}{0.47 \times \mbox{BW}}\right)^{80}}$ ,

where $\Delta f_{MHz}$ is the frequency difference in MHz from the band center and BW is the bandwidth in MHz.

Note

At the large fractional bandwidths of LWA, the window size needed for coherent dedispersion can be prohibitive. For example, at 74 MHz with 19.6 MS/s and a DM or 10 pc / cm^3 this function uses a window size of about 268 million points.

Changed in version 1.0.1: Added a cache for storing the chrip function between subsequent calls

Changed in version 0.6.4: Added support for keeping track of time through the dedispersion process.

lsl.misc.dedispersion.delay(freq, dm)¶: Calculate the relative delay due to dispersion over a given frequency range in Hz for a particular dispersion measure in pc cm^-3. Return the dispersive delay in seconds.

Changed in version 1.1.1: If only a single frequency is provided, the returned delay is relative to infinite frequency.

lsl.misc.dedispersion.get_coherent_sample_size(central_freq, sample_rate, dm)¶: Estimate the number of samples needed to successfully apply coherent dedispersion to a data stream.

lsl.misc.dedispersion.incoherent(freq, waterfall, tInt, dm, boundary='wrap', fill_value=nan)¶

Given a list of frequencies in Hz, a 2-D array of spectra as a function of time (time by frequency), and an integration time in seconds, perform incoherent dedispersion on the data.

The ‘boundary’ keyword is used to control how the boundary is treated. The two options are:

wrap - Wrap the time boundary for each frequency (default)

fill - Fill the data not within the dedispersed time range with
the value specified by the ‘fill_value’ keyword

Changed in version 1.0.3: Added in options for handling the boundary conditions

Catalogs and Sky Map¶

Catalogs¶

New in version 0.2.

LWA astronomical source catalogs.

class lsl.catalog.C3C_Catalog¶

Specific definition for Cambridge 3C source catalogue data file.

parse_file()¶: Read a source catalog data file.

class lsl.catalog.C4C_Catalog¶

Specific definition for Cambridge 4C source catalogue data file.

parse_file()¶: Read a source catalog data file.

class lsl.catalog.Catalog(name)¶

Class representing astronomical source catalog information. This is an abstract class; derived classes must provide a parse_file() method which populates the catalog object with information from file or other source.

Catalog instances support the read-only collections.Mapping interface. That is, they support the read-only methods of the dict built-in type.

static get_directory()¶: Returns the path to the catalog data file directory.

lookup(name)¶

Lookup a source in the catalog.

Param: name - The primary name or alias of the source.

Returns: An object of type CatalogEntry giving the source information,: or None if the name is not found in the catalog.

abstract parse_file()¶: Read catalog information from file into internal data structures.

class lsl.catalog.CatalogEntry(name, position)¶

Represents one source entry in a catalogue.

Contains members:

name - The source name.
position - The source equatorial J2000 position as object
of type transform.CelestialPosition.
alias_list - A list of strings providing alternate names for
the source.

class lsl.catalog.CatalogFactory¶

Get catalog objects by name. Caches the catalog data so that the data file is parsed only once per session.

classmethod get_catalog(name)¶: Returns a Catalog object representing the catalog given by name.

classmethod get_names()¶: Return a list of known catalog names.

class lsl.catalog.F2FGL_Catalog¶

Specific definition for Fermi LAT 2-year point source catalog.

parse_file()¶: Read a source catalogue data file.

class lsl.catalog.LWA_Catalog¶

Specific definition for LWA observation source catalogue data file.

parse_file()¶: Read a source catalog data file.

class lsl.catalog.PKS90_Catalog¶

Specific definition for PKS90 source catalogue data file.

parse_file()¶: Read a source catalog data file.

class lsl.catalog.PKS_Catalog¶

Specific definition for PKS source catalog.

parse_file()¶: Read a source catalog data file.

class lsl.catalog.PSR_Catalog¶

Specific definition for ATNF Pulsar (PSRCAT) catalog. Data file is psrcat.db which can be retreived from: <http://www.atnf.csiro.au/research/pulsar/psrcat/download.html>

parse_file()¶: Read a source catalog data file.

Sky Map¶

New in version 0.2.

Classes and methods to model sky brightness and visibility.

Changed in version 1.2.0: Removed the orignal SkyMap class that uses LFmap at 73.9 MHz Updated SkyMapGSM to use the actual GSM rather than a fit to the GSM Added a new SkyMapLFSM that uses the 5.1 degree resolution LFSM

class lsl.skymap.ProjectedSkyMap(skymap_object, lat, lon, utc_jd)¶

The class for handling the model sky brightness maps over a particular site. This code is the base class for the sky map visible at a specific location. It takes as input a skymap file name and frequency to which the skymap corresponds. It inherits from class SkyMap. It has the following methods: 1. _init_ - takes the array coordinate filename as an input argument. 2. get_direction_cosines - Computes the direction cosines 3. compute_visibile_power - Sums the power for all visible sources in the sky.

compute_visible_power()¶: Compute and return the the total power from visible portion of the sky.

get_direction_cosines()¶: Compute the direction cosines and return the tuple of arrays (l,m,n).

class lsl.skymap.SkyMapGSM(filename=None, freq_MHz=73.9)¶

Extension of the SkyMap class to use the Global Sky Model.

For more information on the Global Sky Model, see: http://space.mit.edu/~angelica/gsm/index.html

Note

This class uses a slightly different interpolation method than the original GSM and introduces a few percent difference at 74 MHz.

Changed in version 1.2.0: Reworked the GSM model to use the actual GSM that has been downsampled to 64 sides rather than the fit.

compute_total_power()¶: Compute and return the the total power from the sky.

normalize_power()¶: Compute the skymap power (total power radiated into 4 pi steradians) into a power at antenna, based on pixel count.

class lsl.skymap.SkyMapLFSM(filename=None, freq_MHz=73.9)¶

Extension of the SkyMap class to use the Low Frequency Sky Model with 5.1 degree resolution.

For more information on the Low Frequency Sky Model, see: https://lda10g.alliance.unm.edu/LWA1LowFrequencySkySurvey/

New in version 1.2.0.

compute_total_power()¶: Compute and return the the total power from the sky.

normalize_power()¶: Compute the skymap power (total power radiated into 4 pi steradians) into a power at antenna, based on pixel count.

Time and Position Transformation¶

New in version 0.2.

Time and position transform objects.

Time¶

class lsl.transform.Time(value, format='MJD', timesys='UTC')¶

Holds an absolute time value and can manipulate the value in various representations.

After creation, a particular time format and time system may be accessed using the appropriate instance member. If marked with ‘(S)’, the Time value may also be updated by setting the member to a new value.

utc_jd (S) - UTC standard Julian day utc_mjd (S) - UTC modified Julian day utc_timet (S) - UTC UNIX timet seconds utc_py_date (S) - UTC python datetime.datetime object utc_ln_date (S) - UTC libnova astro.date object utc_dp (S) - UTC DP samples at 196 MHz utc_mcs - UTC MCS MJD/MPM pair utc_str - UTC ISO8601 calendar string format

tai_jd (S) - TAI standard Julian day tai_mjd (S) - TAI modified Julian day tai_timet (S) - TAI UNIX timet seconds

static date_ln_to_py(lnDate)¶: Convert libnova astro.date object into a python datetime.datetime object.

static date_py_to_ln(pyDate)¶: Convert python datatime.datetime object into a libnova astro.date object.

classmethod from_system()¶: Factory method to create a Time instance from current system clock value.

property tai_jd¶: Time value formatted as TAI standard julian day (float).

property tai_mjd¶: Time value formatted as TAI modified julian day (float).

property tai_timet¶: Time value formatted as TAI UNIX timet seconds.

property utc_jd¶: Time value formatted as UTC standard julian day (float).

property utc_ln_date¶: Time value formatted as UTC calendar astro.date object.

property utc_mjd¶: Time value formatted as UTC modified julian day (float).

property utc_py_date¶: Time value formattes as UTC calendar datetime.datetime object.

property utc_str¶: Time value formatted as UTC ISO 8601 calendar string.

property utc_timet¶: Time value formatted as UTC UNIX timet seconds.

Celstial Positions¶

class lsl.transform.CelestialPosition(value, format='EQU', epoch='J2000', name='')¶

Holds a celestial object position value and can manipulate the value in various representations.

After creation, the celestial coordinates may be accessed in different formats and epoch by using the appropriate instance member. If marked with ‘(S)’, the Time value may also be updated by setting the member to a new value.

j2000_equ (S) - J2000 equatorial coordinates j2000_gal (S) - J2000 galactic coordinates j2000_ecl (S) - J2000 ecliptic coordinates

b1950_equ (S) - B1950 equatorial coordinates

The instance methods apparent_equ() and apparent_ecl() may be used to get the apparent equatorial or ecliptic coordinates for a particular time.

apparent_ecl(time_)¶: Return position formatted as apparent ecliptic coordinates. The ‘time’ parameter should be set to a Time instance providing the time of interest. Return alue is object of type astro.ecl_posn.

apparent_equ(time_)¶: Return position formatted as apparent equatorial coordinates. The ‘time’ parameter should be set to a Time instance providing the time of interest. Return value is object of type astro.equ_posn.

property b1950_equ¶: Position formatted as B1950 equatorial coordinates. Value is object of type astro.equ_posn.

property j2000_ecl¶: Position formatted as J2000 ecliptic coordinates. Value is object of type astro.ecl_posn.

property j2000_equ¶: Position formatted as J2000 equatorial coordinates. Value is object of type astro.equ_posn.

property j2000_gal¶: Position formatted as J2000 galactic coordinates. Value is object of type astro.gal_posn.

class lsl.transform.PlanetaryPosition(name)¶

Holds a solar, lunar, or planetary position value and can manipulate the value in various representations.

The instance methods apparent_equ() and apparent_ecl() may be used to get the apparent equatorial or ecliptic coordinates for a particular time.

apparent_ecl(time_)¶: Position formatted as apparent ecliptic coordinates. The ‘time’ parameter should be set to a Time instance providing the time of interest. Return value is object of type astro.ecl_posn.

apparent_equ(time_)¶: Position formatted as apparent equatorial coordinates. The ‘time’ parameter should be set to a Time instance providing the time of interest. Return value is object of type astro.equ_posn.

class lsl.transform.SkyPosition¶

Base abstract class for representing positions on the sky.

apparent_ecl(time_)¶: Return position formatted as apparent ecliptic coordinates. The ‘time’ parameter should be set to a Time instance providing the time of interest. Return alue is object of type astro.ecl_posn.

abstract apparent_equ(time_)¶: Return position formatted as apparent equatorial coordinates. The ‘time’ parameter should be set to a Time instance providing the time of interest. Return value is object of type astro.equ_posn.

class lsl.transform.PointingDirection(source, site)¶

Represent a target source object pointing direction for a particular ground site location.

Each PointingDirection instance pairs a celestial position with a ground observation site position. Each instance contains a ‘source’ member reference of type CelestialPosition or PlanetaryPosition and a ‘site’ member reference of type GeographicalPosition.

The instance methods hrz() and dir_cos() may be called to get the pointing direction as horizontal coordinates or direction cosine components for a particular time of interest. The rst() method may be called to get the rise, set, and transit ephemeris times.

dir_cos(time_)¶: Return the pointing direction as three direction cosine components. The ‘time’ parameter should be set to a Time instance providing the time of interest. Return value is a tuple (l, m, n) of direction cosine components.

hrz(time_)¶: Return the pointing direction in horizontal coordinates as type astro.hrz_posn. The ‘time’ parameter should be set to a Time instance providing the time of interest.

rst(time_)¶: Return the rise, set, and transit ephemeris times. The ‘time’ parameter should be set to a Time instance providing the time of interest. Return value is an object of type astro.rst_time, or None if the source is circumpolar.

Geographic Positions¶

class lsl.transform.GeographicalPosition(value, format='GEO', name='')¶

Holds a geographical position valuee and can manipulate the value in various representations.

After creation, the celestial coordinates may be accessed in different formats and epoch by using the appropriate instance member. If marked with ‘(S)’, the Time value may also be updated by setting the member to a new value.

geo (S) - longitude and latitude degrees, elevation meters ecef (S) - Earth centered rectilinear coordinates

property ecef¶: Position formatted as ECEF rectagular coordinates. Value is object of type astro.rect_posn.

property geo¶: Position formatted as geodedic longitude, latitude, elevation. Value is object of type astro.geo_posn.

sidereal(time_)¶: Return the apparent sidereal time for this location. The ‘time’ parameter should be set to a Time instance providing the time of interest. Returns sidereal time as a float in range [0.0, 24.0).

Math Utilities¶

Useful math functions for LWA work.

lsl.misc.mathutils.cimag(cmplx)¶: Return the imaginary rectilinear component from complex values expressed in polar form (magnitude, phase).

lsl.misc.mathutils.cmagnitude(cmplx)¶: Return the polar magnitudes of complex values.

lsl.misc.mathutils.cphase(cmplx)¶: Return the polar phases of complex values as radians.

lsl.misc.mathutils.cpolar(cmplx)¶: Return the polar (magnitude, phase) representation of complex values (real, imaginary). The return value is an array of shape (N,2), where N is the length of the cmplx input array.

lsl.misc.mathutils.creal(cmplx)¶: Return the real rectilinear component from complex values expressed in polar form (magnitude, phase).

lsl.misc.mathutils.crect(cmplx)¶: Return the rectilinear (real, imaginary) representation of complex values (magnitude, phase).

lsl.misc.mathutils.downsample(vector, factor, rescale=True)¶: Downsample (i.e. co-add consecutive numbers) a vector by an integer factor. Trims the input timeseries to be a multiple of the downsample factor, if needed. If rescale == True, then divides each sum by factor to produce a mean value, otherwise just adds the values in the vector.

lsl.misc.mathutils.from_dB(dB)¶: Convert from decibels to linear units.

lsl.misc.mathutils.gaussian1d(height, center, width)¶

Return a function that generates a 1-D gaussian with the specified height, mean, and standard deviation.

Example: >>> height = 1 >>> center = 5.0 >>> width = 2.1 >>> gauFnc = guassian1d(height, center, width) >>> value = gauFnc(numpy.arange(0, 100))

Based on: http://code.google.com/p/agpy/source/browse/trunk/agpy/gaussfitter.py

lsl.misc.mathutils.gaussian2d(height, centerX, centerY, widthMaj, widthMin, angle=0.0)¶

Return a function that generates a 2-D gaussian with the specified height, mean (for both X and Y), standard deviation (for both major and minor axes), and rotation angle from the X axis in degrees.

Based on: http://code.google.com/p/agpy/source/browse/trunk/agpy/gaussfitter.py

lsl.misc.mathutils.gaussparams(data, x=None, y=None)¶: Estimate the parameters (height, center, width) for a gaussian. The return order is:

1-D: height, center, width 2-D: height, center x, center y, width x, width y, position angle

Note

The 2-D fits always return a position angle of zero since the routine decomposes the process into two 1-D fits.

lsl.misc.mathutils.ndft(t, x)¶: Given a list of times and a list of data values, compute a non-uniform discrete Fourier transform (NDFT) of the data. Returns a two element tuple of frequency and the complex NDFT result.

lsl.misc.mathutils.regrid(x, y, newx, allow_extrapolation=False, method='spline')¶

Regrid data from x,y onto newx. If allow_extrapolation is True, extrapolation is attempted if the method supports it. Supported methods are:

linear

spline

Use of this function may require the scipy extension package.

lsl.misc.mathutils.smooth(x, window_len=10, window='hanning')¶

Smooth the data using a window with requested size. Stolen from SciPy Cookbook at http://www.scipy.org/Cookbook/SignalSmooth

This method is based on the convolution of a scaled window with the signal. The signal is prepared by introducing reflected copies of the signal (with the window size) in both ends so that transient parts are minimized in the begining and end part of the output signal.

Input:

x: the input signal
window_len: the dimension of the smoothing window
window: the type of window from ‘flat’, ‘hanning’, ‘hamming’,
‘bartlett’, ‘blackman’ flat window will produce a moving average smoothing.

Output:

the smoothed signal

Example:

>>> from numpy import *
>>> t=linspace(-2,2,0.1)
>>> x=sin(t)+randn(len(t))*0.1
>>> y=smooth(x)

Robust Statistics¶

Changed in version 0.4.0: Function names have been changed in this module and new function added. See the below for more details.

Small collection of robust statistical estimators based on functions from Henry Freudenriech (Hughes STX) statistics library (called ROBLIB) that have been incorporated into the AstroIDL User’s Library. Function included are:

biweight_mean - biweighted mean estimator

mean - robust estimator of the mean of a data set

mode - robust estimate of the mode of a data set using the half-sample
method

std - robust estimator of the standard deviation of a data set

checkfit - return the standard deviation and biweights for a fit in order
to determine its quality

linefit - outlier resistant fit of a line to data

polyfit - outlier resistant fit of a polynomial to data

For the fitting routines, the coefficients are returned in the same order as numpy.polyfit, i.e., with the coefficient of the highest power listed first.

For additional information about the original IDL routines, see: http://idlastro.gsfc.nasa.gov/contents.html#C17

lsl.statistics.robust.biweight_mean(inputData, axis=None, dtype=None)¶

Calculate the mean of a data set using bisquare weighting.

Based on the biweight_mean routine from the AstroIDL User’s Library.

Changed in version 1.0.3: Added the ‘axis’ and ‘dtype’ keywords to make this function more compatible with numpy.mean()

lsl.statistics.robust.checkfit(inputData, inputFit, epsilon, delta, bisquare_limit=6.0)¶

Determine the quality of a fit and biweights. Returns a tuple with elements:

Status

Robust standard deviation analog

Fractional median absolute deviation of the residuals

Number of input points given non-zero weight in the calculation

Bisquare weights of the input points

Residual values scaled by sigma

This function is based on the rob_checkfit routine from the AstroIDL User’s Library.

lsl.statistics.robust.linefit(inputX, inputY, max_iter=25, bisector=False, bisquare_limit=6.0, close_factor=0.03)¶

Outlier resistance two-variable linear regression function.

Based on the robust_linefit routine in the AstroIDL User’s Library.

lsl.statistics.robust.mean(inputData, cut=3.0, axis=None, dtype=None)¶: Robust estimator of the mean of a data set. Based on the resistant_mean function from the AstroIDL User’s Library.

Changed in version 1.2.1: Added a ValueError if the distriubtion is too strange

Changed in version 1.0.3: Added the ‘axis’ and ‘dtype’ keywords to make this function more compatible with numpy.mean()

lsl.statistics.robust.mode(inputData, axis=None, dtype=None)¶: Robust estimator of the mode of a data set using the half-sample mode.

lsl.statistics.robust.polyfit(inputX, inputY, order, max_iter=25)¶

Outlier resistance two-variable polynomial function fitter.

Based on the robust_poly_fit routine in the AstroIDL User’s Library.

lsl.statistics.robust.std(inputData, zero=False, axis=None, dtype=None)¶

Robust estimator of the standard deviation of a data set.

Based on the robust_sigma function from the AstroIDL User’s Library.

Changed in version 1.2.1: Added a ValueError if the distriubtion is too strange

Changed in version 1.0.3: Added the ‘axis’ and ‘dtype’ keywords to make this function more compatible with numpy.std()

Statistical Tests¶

New in version 0.4.0.

Collection of statistical tests not found in any of the common python libraries.

lsl.statistics.stattests.wald_wolfowitz(inputData)¶: Wald-Wolfowitz test of randomness. Given a numpy array of values compute the probability that the values are mutially independent.

See also

http://en.wikipedia.org/wiki/Wald%E2%80%93Wolfowitz_runs_test

Module and Data Paths¶

Module to set up path information for the LWA Software Library. Two variables are defined by this module:

MODULE

DATA

MODULE: specifies the absolute path to the module
DATA: the absolute path to the data directory where data files are stored

Busy Indicator¶

New in version 1.0.0.

Module to make a blinking ASCII busy indicator.

class lsl.common.busy.BusyIndicator(message='Busy', interval=0.5, dots=3)¶

Object to make a ASCII busy indicator for use with various long- run tasks that don’t have a way of calculating how long they will take.

Example Usage:

>>> from busy import BusyIndicator
>>> bi = BusyIndicator()
>>> bi.start()
>>> longRunningTask()
>>> bi.stop()

start()¶: Start the indicator running.

stop(success=True)¶: Stop the indicator and display a ‘Done’ or ‘Failed’ message depending on whether or not the ‘success’ keyword is True.

Note

This can take up to one BusyIndicator.interval to complete.

Color Support¶

New in version 1.2.1.

Module to help display color on the command line of ANSI-compliant termainals.

..versionadded:: 1.2.1

lsl.common.color.colorfy(text)¶

Given a string encoded with color and/or style information, return a string with embedded ANSI terminal codes. For example: {{%red text}} {{%underline underline}} will return the text ‘text underline’ with ‘text’ displayed as red and ‘underline’ underlined.

Valid colors are:

black
red
green
yellow
blue
magenta
cyan
white

Valid type styles are:

bold
underline
blink
reverse

Note

Background colors can be set by appending ‘bkg-‘ to the color name.

Progress Bar¶

New in version 0.4.0.

Module to make an ASCII progress bar.

class lsl.common.progress.ProgressBar(max=100, span=70, sym='=', print_percent=True)¶

Object to make a ASCII progress bar for use with various long- run tasks.

Example Usage:

>>> import sys
>>> from progess import ProgressBar
>>> pb = ProgressBar()
>>> pb.inc()
>>> sys.stdout.write(pb.show())
>>> sys.stdout.flush()

dec(amount=1)¶: Decrement the progress bar’s internal counter by some amount. The default is one.

inc(amount=1)¶: Increment the progress bar’s internal counter by some amount. The default is one.

show()¶: Build a string representation of the progress bar and return it.

class lsl.common.progress.ProgressBarPlus(max=100, span=70, sym='=', print_percent=True)¶

Extended version of the ProgressBar class that has a crude time estimator.

Example Usage:

>>> import sys
>>> from progess import ProgressBar
>>> pb = ProgressBar()
>>> pb.inc()
>>> sys.stdout.write(pb.show())
>>> sys.stdout.flush()

Note

The timing feature is only active when the inc()/dec() functions are called.

New in version 0.6.4.

show()¶: Build a string representation of the progress bar and return it.

startTimer()¶: Initialize the timer.

LWA-Specific Utilites¶

Defining Single Station Observations and Observation Metadata¶

Session Definition Files¶

Module that contains all of the relevant class to build up a representation of a session definition file as defined in MCS0030v5. The hierarchy of classes is:

Project - class that holds all of the information about the project (including
the observer) and one or more sessions. Technically, a SD file has only one session but this approach allows for the generation of multiple SD files from a single Project object.

Observer - class that hold the observer’s name and numeric ID

Session - class that holds all of the observations associated with a particular
DP output.

Observations - class that hold information about a particular observation. It
includes a variety of attributes that are used to convert human- readable inputs to SDF data values. The observation class is further subclasses into:

TBW - class for TBW observations

TBN - class for TBN observations

DRX - class for general DRX observation, with sub-classes: * Solar - class for solar tracking * Jovian - class for Jovian tracking

Stepped - class for stepped observations

BeamStep - class that holds the information about a particular step in a Stepped
Observation

All of the classes, except for Stepped and BeamStep, are complete and functional. In addition, most class contain ‘validate’ attribute functions that can be used to determine if the project/session/observation are valid or not given the constraints of the DP system.

In addition to providing the means for creating session definition files from scratch, this module also includes a simple parser for SD files.

Changed in version 2.0.0: Added support for astropy.time.Time and astropy.coordinates.Angle instances

Changed in version 1.0.0: Added the get_observation_start_stop() function. Renamed parse_timeString() to parse_time() parse_time() can now accept dates/times as timezone-aware datetime instances Observations can now be initialized with durations as timedelta instances Observations can now be initialized with RA/dec/az/alt as ephem.hours and ephem.degrees instances

Session Structure¶

lsl.common.sdf (DP-based stations) and lsl.common.sdfADP (ADP-based stations) provide means to represent a set of observations as Python objects. For each lsl.common.sdf.Project, there is:

An observer (lsl.common.sdf.Observer)

The project office comments (lsl.common.sdf.ProjectOffice)

A single session that defines the SDF (lsl.common.sdf.Session)

The session contains one or more observerions (lsl.common.sdf.Observation). Each observing mode supported by the LWA is sub-classed (see below).

class lsl.common.sdf.Project(observer, name, id, sessions=None, comments=None, project_office=None)¶

Class to hold all the information about a specific session for a project/proposal.

Changed in version 1.2.1: Added a new writeto() method to directly write the SDF to a file.

append(newSession)¶: Add a new Session to the list of sessions.

render(session=0, verbose=False)¶: Create a session definition file that corresponds to the specified session. Returns the SD file’s contents as a string.

update()¶: Update the various sessions that are part of this project.

validate(verbose=False)¶: Examine all of the sessions and all of their observations to check for validity. If everything is valid, return True. Otherwise, return False.

writeto(filename, session=0, verbose=False, overwrite=False)¶: Create a session definition file that corresponds to the specified session and write it to the provided filename.

class lsl.common.sdf.Observer(name, id, first=None, last=None)¶: Class to hold information about an observer.

class lsl.common.sdf.ProjectOffice(project=None, sessions=None, observations=None)¶: Class to hold comments from the LWA object office. This class isn’t really needed to create SD files, but it is helpful for parsing SD files.

class lsl.common.sdf.Session(name, id, observations=None, data_return_method='DRSU', comments=None, station=<LWAStation id='VL', name='LWA1', lat=34:04:08.0, long=-107:37:42.1, elev=2133.6, pressure=0.0, horizon=0:00:00.0, antennas=[...], interface=<LSLInterface backend='lsl.common.dp', mcs='lsl.common.mcs', sdf='lsl.common.sdf', metabundle='lsl.common.metabundle', sdm='lsl.common.sdm'>>)¶

Class to hold all of the observations in a session.

append(newObservation)¶: Add a new Observation to the list of observations.

set_mib_record_interval(component, interval)¶

Set the record interval for one of the level-1 subsystems (ASP, DP_, etc.) to a particular value in minutes. A KeyError is raised if an invalid sub-system is specified.

Special Values are:

-1 = use the MCS default interval
0 = never record the MIB entries (the entries are still updated, however)

set_mib_update_interval(component, interval)¶

Set the update interval for one of the level-1 subsystems (ASP, DP_, etc.) to a particular value in minutes. A KeyError is raised if an invalid sub-system is specified.

Special Values are:

-1 = use the MCS default interval
0 = request no updates to the MIB entries

property spectrometer_channels¶: Number of spectrometer channesl to output, 0 is disables.

property spectrometer_integration¶: Number of FFT windows per spectrometer integration, 0 to disable.

property spectrometer_metatag¶: Spectrometer polarization selection.

update()¶: Update the various observations in the session.

validate(verbose=False)¶: Examine all of the observations associated with the session to check for validity. If everything is valid, return True. Otherwise, return False.

class lsl.common.sdf.Observation(name, target, start, duration, mode, ra, dec, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Class to hold the specifics of an observations. It currently handles TBW, TBN, TRK_RADEC, TRK_SOL, TRK_JOV, and Stepped

Changed in version 1.0.0: Added support for RA/dec values as ephem.hours/ephem.degrees instances

property dec¶: Target dec. (J2000).

property duration¶: Duration in seconds.

estimate_bytes()¶: Place holder for functions that return the estimate size of the data set being defined by the observation.

property fixed_body¶: Place holder for functions that return ephem.Body objects (or None) that define the pointing center of the observation.

property frequency1¶: Tuning 1 frequency in Hz.

property frequency2¶: Tuning 2 frequency in Hz.

get_beam_type()¶: Return a valid value for beam type based on whether maximum S/N beam forming has been requested.

property ra¶: Target RA (J2000).

property start¶: Start time.

property target_visibility¶: Place holder for functions that return the fractional visibility of the target during the observation period.

update()¶: Update the computed parameters from the string values.

validate(verbose=False)¶: Place holder for functions that evaluate the observation and return True if it is valid, False otherwise.

Observing Modes¶

class lsl.common.sdf.TBW(name, target, start, samples, bits=12, comments=None)¶

Sub-class of Observation specifically for TBW observations. It features a reduced number of parameters needed to setup the observation and provides extra information about the number of data bits and the number of samples.

Note

TBW read-out times in ms are calculated using (samples/196000+1)*5000 per MCS

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string)
integer number of samples

Optional Keywords:

bits - number of data bits (4 or 12)
comments - comments about the observation

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For TBW:

bytes = samples / samplesPerFrame * 1224 bytes * 260 stands

validate(verbose=False)¶: Evaluate the observation and return True if it is valid, False otherwise.

class lsl.common.sdf.TBN(name, target, start, duration, frequency, filter, gain=- 1, comments=None)¶

Sub-class of Observation specifically for TBN observations. It features a reduced number of parameters needed to setup the observation.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation frequency (Hz)
integer filter code

Optional Keywords:

comments - comments about the observation

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For TBN:

bytes = duration * sample_rate / 512 * 1048 bytes * 260 stands * 2 pols.

validate(verbose=False)¶

Evaluate the observation and return True if it is valid, False otherwise.

..note::: This version of sdf allows for TBN tuning between 5 and 93 MHz.

class lsl.common.sdf.DRX(name, target, start, duration, ra, dec, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Sub-class of Observation specifically for DRX-style observations.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation RA in hours, J2000.0 or ephem.hours instance
observation Dec in degrees, J2000.0 or ephem.hours instance
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
comments - comments about the observation

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For DRX:

bytes = duration * sample_rate / 4096 * 4128 bytes * 2 tunings * 2 pols.

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is an all-sky mode.

set_beamdipole_mode(stand, beam_gain=0.04, dipole_gain=1.0, pol='X')¶

Convert the current observation to a ‘beam-dipole mode’ observation with the specified stand. Setting the stand to zero will disable the ‘beam-dipole mode’ for this observation’.

Keywords:

beam_gain - BAM gain to use for each dipole in the beam
default: 0.04; range: 0.0 to 1.0
dipole_gain - BAM gain to use for the single dipole
default: 1.0; range: 0.0 to 1.0
pol - Polarization to record default: “X”

property target_visibility¶: Return the fractional visibility of the target during the observation period.

validate(verbose=False)¶: Evaluate the observation and return True if it is valid, False otherwise.

class lsl.common.sdf.Solar(name, target, start, duration, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Sub-class of DRX specifically for Solar DRX observations. It features a reduced number of parameters needed to setup the observation.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
comments - comments about the observation

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is either TBN or TBW.

class lsl.common.sdf.Jovian(name, target, start, duration, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Sub-class of DRX specifically for Jovian DRX observations. It features a reduced number of parameters needed to setup the observation.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
comments - comments about the observation

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is either TBN or TBW.

class lsl.common.sdf.Stepped(name, target, start, filter, steps=None, is_radec=True, gain=- 1, comments=None)¶

Sub-class of Observation for dealing with STEPPED-mode observations. It features a reduced number of parameters needed to setup the observation and added support for the individual steps.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
integer filter code

Optional Keywords:

steps - array of BeamStep objects that specify the different steps
comments - comments about the observation

append(newStep)¶: Add a new BeamStep step to the list of steps.

property duration¶: Parse the list of BeamStep objects to get the total observation duration as the number of seconds in that period.

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For DRX:

bytes = duration * sample_rate / 4096 * 4128 bytes * 2 tunings * 2 pols.

set_beamdipole_mode(stand, beam_gain=0.04, dipole_gain=1.0, pol='X')¶

Convert the current observation to a ‘beam-dipole mode’ observation with the specified stand. Setting the stand to zero will disable the ‘beam-dipole mode’ for this observation’.

Keywords:

beam_gain - BAM gain to use for each dipole in the beam
default: 0.04; range: 0.0 to 1.0
dipole_gain - BAM gain to use for the single dipole
default: 1.0; range: 0.0 to 1.0
pol - Polarization to record default: “X”

property target_visibility¶: Return the fractional visibility of the target during the observation period.

update()¶: Update the computed parameters from the string values.

validate(verbose=False)¶: Evaluate the observation and return True if it is valid, False otherwise.

class lsl.common.sdf.BeamStep(c1, c2, duration, frequency1, frequency2, is_radec=True, max_snr=False, spec_delays=None, spec_gains=None)¶

Class for holding all of the information (pointing center, tuning frequencies, etc.)associated with a particular step.

Required Keywords:

pointing coordinate 1 (RA [hours] or azimuth [degrees] or ephem.hours/ephem.degrees instance)
pointing coordinate 2 (dec or elevation/altitude [degrees] or ephem.degrees instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)

Optional Keywords:

is_radec - whether the coordinates are in RA/Dec or Az/El pairs (default=RA/Dec)
max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
spec_delays - 520 list of delays to apply for each antenna
spec_gains - 260 by 2 by 2 list of gains ([[XY, XY], [YX, YY]]) to apply for each antenna

Note

If spec_delays is specified, spec_gains must also be specified. Specifying both spec_delays and spec_gains overrides the max_snr keyword.

Changed in version 1.0.0: Added support for azimuth/altitude and RA/dec values as ephem.hours/ephem.degrees instances

property c1¶: Coordinate 1 - hours (J2000) if RA, degrees if azimuth.

property c2¶: Coordinate 2 - degrees (J2000) if dec., degrees if elevation.

property duration¶: Duration in seconds.

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is either TBN or TBW.

property frequency1¶: Tuning 1 frequency in Hz.

property frequency2¶: Tuning 2 frequency in Hz.

get_beam_type()¶: Return a valid value for beam type based on whether maximum S/N beam forming has been requested.

update()¶: Update the settings.

validate(verbose=False)¶: Evaluate the step and return True if it is valid, False otherwise.

MCS Metadata Tarball Utilities¶

Module for working with an MCS meta-data tarball and extracting the useful bits out it and putting those bits into Python objects, e.g, lsl.common.stations.LWAStation and lsl.common.sdm.SDM.

lsl.common.metabundle.get_asp_configuration(tarname, which='beginning')¶: Given an MCS meta-data tarball, extract the ASP MIB contained in it and return a dictionary of values for the filter, AT1, AT2, and ATSplit. The ‘which’ keyword is used to specify whether or not the configuration returned is at the beginning (default) or end of the session.

New in version 0.6.5.

lsl.common.metabundle.get_asp_configuration_summary(tarname, which='beginning')¶: Similar to get_asp_configuration, but returns only a single value for each of the four ASP paramters: filter, AT, AT2, and ATSplit. The values are based off the mode of the parameter.

New in version 0.6.5.

lsl.common.metabundle.get_command_script(tarname)¶: Given an MCS meta-data tarball, extract the command script and parse it. The commands are returned as a list of dictionaries (one dictionary per command).

lsl.common.metabundle.get_observation_spec(tarname, obs_id=None)¶: Given an MCS meta-data tarball, extract one or more observation specification file (MCS0030, Section 6) and return a list of dictionaries corresponding to each OBS file. If the obs_id keyword is set to a list of observation numbers, only observations matching the numbers in obs_id are returned.

lsl.common.metabundle.get_sdf(tarname)¶: Given an MCS meta-data tarball, extract the session specification file, the session meta-data file, and all observation specification files to build up a SDF-representation of the session.

Note

This function returns a full lsl.common.sdf.Project instance with the session in question stored under project.sessions[0] and the observations under project.sessions[0].observations.

lsl.common.metabundle.get_sdm(tarname)¶

Given an MCS meta-data tarball, extract the information stored in the dynamic/sdm.dat file and return a lsl.common.sdm.SDM instance describing the dynamic condition of the station.

If a sdm.dat file cannot be found in the tarball, None is returned.

lsl.common.metabundle.get_session_metadata(tarname)¶: Given an MCS meta-data tarball, extract the session meta-data file (MCS0030, Section 7) and return a dictionary of observations that contain dictionaries of the OP_TAG (tag), DRSU Barcode (drsu), OBS_OUTCOME (outcome), and the MSG (msg).

Changed in version 0.6.5: Update to the new _metadata.txt format

lsl.common.metabundle.get_session_spec(tarname)¶: Given an MCS meta-data tarball, extract the session specification file (MCS0030, Section 5) and return a dictionary of parameters.

lsl.common.metabundle.get_station(tarname, apply_sdm=True)¶

Given an MCS meta-data tarball, extract the information stored in the ssmif.dat file and return a lsl.common.stations.LWAStation object. Optionally, update the lsl.common.stations.Antenna instances associated whith the LWAStation object using the included SDM file.

If a ssmif.dat file cannot be found in the tarball, None is returned.

lsl.common.metabundle.is_valid(tarname, verbose=False)¶: Given a filename, see if it is valid metadata tarball or not.

New in version 1.2.0.

lsl.common.metabundle.read_cs_file(filename)¶: Read in a command script file (MCS0030, currently undocumented) and return the data as a list of dictionaries.

lsl.common.metabundle.read_obs_file(filename)¶: Read in a observation specification file (MCS0030, Section 6) and return the data as a dictionary.

lsl.common.metabundle.read_ses_file(filename)¶: Read in a session specification file (MCS0030, Section 5) and return the data as a dictionary.

Supporting Functions¶

Conversion to/from MJD and MPM¶

These functions convert Python datetime instances to modified Julian Data (MJD) and milliseconds past midnight (MPM) pairs.

lsl.common.mcs.datetime_to_mjdmpm(dt)¶

Convert a UTC datetime instance to a MJD, MPM pair (returned as a two-element tuple).

Based off: http://paste.lisp.org/display/73536

Changed in version 2.0.1: Better support for time zone-aware datetime instances

New in version 0.5.2.

lsl.common.mcs.mjdmpm_to_datetime(mjd, mpm, tz=None)¶: Convert a MJD, MPM pair to a naive datetime instance. If tz is not None the value is converted to a time zone-aware instance in the specified time zone.

Changed in version 2.0.1: Added the tz keyword and fixed the documentation.

New in version 0.5.2.

Specifiying Delay and Gains for the Digital Processor¶

These functions are intended to help define observations that are run in Stepped mode with the beamforming method set to “SPEC_DELAYS_GAINS”.

lsl.common.mcs.delay_to_mcsd(delay)¶: Given a delay in ns, convert it to a course and fine portion and into the form expected by MCS in a custom beamforming SDF (little endian 16.12 unsigned integer).

New in version 0.6.3.

lsl.common.mcs.mcsd_to_delay(delay)¶: Given delay value from an OBS_BEAM_DELAY field in a custom beamforming SDF, return the delay in ns.

New in version 0.6.3.

lsl.common.mcs.gain_to_mcsg(gain)¶: Given a gain (between 0 and 1), convert it to a gain in the form expected by MCS in a custom beamforming SDF (little endian 16.1 signed integer).

lsl.common.mcs.mcsg_to_gain(gain)¶: Given a gain value from an OBS_BEAM_GAIN field in a custom beamforming SDF, return the decimal equivalent.

New in version 0.6.3.

Interpretting MCS Numeric Codes¶

These functions convert various MCS numeric codes found in the metatdata into strings.

lsl.common.mcs.status_to_string(code)¶: Convert a numerical MCS status code to a string.

lsl.common.mcs.summary_to_string(code)¶: Convert a numerical MCS overall status code to an explination.

lsl.common.mcs.sid_to_string(sid)¶: Convert a MCS subsystem ID code into a string.

lsl.common.mcs.cid_to_string(cid)¶: Convert a MCS command code into a string.

lsl.common.mcs.mode_to_string(mode)¶: Convert a MCS numeric observing mode into a string.

LWA Swarm Observations¶

Interferometer Definition Files¶

Module that contains all of the relevant class to build up a representation of a interferometer definition file. The hierarchy of classes is:

Project - class that holds all of the information about the project (including
the observer) and one or more runs. Technically, a ID file has only one run but this approach allows for the generation of multiple SD files from a single Project object.

Observer - class that hold the observer’s name and numeric ID

Run - class that holds all of the scans associated and the associated
correlator setup for a with a particular interferometer run

Scan - class that hold information about a particular scan. It
includes a variety of attributes that are used to convert human- readable inputs to SDF data values. The scan class is further subclasses into:

DRX - class for general DRX scan, with sub-classes: * Solar - class for solar tracking * Jovian - class for Jovian tracking

Most class contain ‘validate’ attribute functions that can be used to determine if the project/run/scan are valid or not given the constraints of the ADP system.

In addition to providing the means for creating interferometer definition files from scratch, this module also includes a simple parser for ID files.

Changed in version 2.0.0: Added support for astropy.time.Time and astropy.coordinates.Angle instances

New in version 1.2.4.

Run Structure¶

Similar to the lsl.common.sdf module, lsl.common.idf provides a means to represent a set of scans using the LWA Swarm interferometer as Python objects. For each lsl.common.idf.Project, there is:

An observer (lsl.common.idf.Observer)

The project office comments (lsl.common.idf.ProjectOffice)

A single run that defines the IDF (lsl.common.idf.Run)

The run contains one or more scans (lsl.common.idf.Scan). Each observing mode supported by the LWA Swarm is sub-classed (see below).

class lsl.common.idf.Project(observer, name, id, runs=None, comments=None, project_office=None)¶

Class to hold all the information about a specific interferometer run for a project/proposal.

append(newRun)¶: Add a new run to the list of runs.

generate_sdfs(starting_session_id=1, run=0, verbose=False)¶: Convert the ID file into a collection of lsl.common.sdfADP.Project instances that can be used to write SD files.

render(run=0, verbose=False)¶: Create a run definition file that corresponds to the specified run. Returns the ID file’s contents as a string.

update()¶: Update the various runs that are part of this project.

validate(verbose=False)¶: Examine all of the runs and all of their scans to check for validity. If everything is valid, return True. Otherwise, return False.

writeto(filename, run=0, verbose=False, overwrite=False)¶: Create a run definition file that corresponds to the specified run and write it to the provided filename.

class lsl.common.idf.Observer(name, id, first=None, last=None)¶: Class to hold information about an observer.

class lsl.common.idf.ProjectOffice(project=None, runs=None, scans=None)¶: Class to hold comments from the LWA object office. This class isn’t really needed to create ID files, but it is helpful for parsing ID files.

class lsl.common.idf.Run(name, id, scans=None, data_return_method='DRSU', comments=None, correlator_channels=512, correlator_inttime=1.0, correlator_basis='linear', stations=[<LWAStation id='VL', name='LWA1', lat=34:04:08.0, long=-107:37:42.1, elev=2133.6, pressure=0.0, horizon=0:00:00.0, antennas=[...], interface=<LSLInterface backend='lsl.common.dp', mcs='lsl.common.mcs', sdf='lsl.common.sdf', metabundle='lsl.common.metabundle', sdm='lsl.common.sdm'>>, <LWAStation id='SV', name='LWASV', lat=34:20:54.1, long=-106:53:08.8, elev=1477.8, pressure=0.0, horizon=0:00:00.0, antennas=[...], interface=<LSLInterface backend='lsl.common.adp', mcs='lsl.common.mcsADP', sdf='lsl.common.sdfADP', metabundle='lsl.common.metabundleADP', sdm='lsl.common.sdmADP'>>])¶

Class to hold all of the scans in an interferometer run.

append(newScan)¶: Add a new Scan to the list of scans.

property correlator_basis¶: Correlator output polarization basis.

property correlator_channels¶: Number of correlator channels to use.

property correlator_inttime¶: Correlator integration time in seconds.

property stations¶: List of LWA stations to use in the interferometer.

update()¶: Update the various scans in the run.

validate(verbose=False)¶: Examine all of the scans associated with the run to check for validity. If everything is valid, return True. Otherwise, return False.

class lsl.common.idf.Scan(target, intent, start, duration, mode, ra, dec, frequency1, frequency2, filter, gain=- 1, pm=[0.0, 0.0], comments=None)¶

Class to hold the specifics of a scans. It currently handles TRK_RADEC, TRK_SOL, and TRK_JOV.

add_alt_phase_center(target_or_apc, intent=None, ra=None, dec=None, pm=None)¶: Add an alternate phase center to the scan.

property dec¶: Target dec. (J2000).

property duration¶: Duration in seconds.

estimate_bytes()¶: Estimate the data volume for the specified type and duration of scans. For DRX:

bytes = duration * sample_rate / 4096 * 4128 bytes * 2 tunings * 2 pols.

property fixed_body¶: Return an ephem.Body object corresponding to where the scan is pointed. None if the scan mode is TBN.

property frequency1¶: Tuning 1 frequency in Hz.

property frequency2¶: Tuning 2 frequency in Hz.

property intent¶: Obsevational intent.

property pm¶: Target proper motion in mas/yr.

property ra¶: Target RA (J2000).

property start¶: Start time.

property target_visibility¶: Return the fractional visibility of the target during the scan period.

update()¶: Update the computed parameters from the string values.

validate(verbose=False)¶: Evaluate the scan and return True if it is valid, False otherwise.

Observing Modes¶

class lsl.common.idf.DRX(target, intent, start, duration, ra, dec, frequency1, frequency2, filter, gain=- 1, pm=[0.0, 0.0], comments=None)¶

Required Arguments:

scan target
scan intent
scan start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
scan duration (HH:MM:SS.SSS string or timedelta instance)
scan RA in hours, J2000.0 or ephem.hours instance
scan Dec in degrees, J2000.0 or ephem.hours instance
scan tuning frequency 1 (Hz)
scan tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

comments - comments about the scan

class lsl.common.idf.Solar(target, intent, start, duration, frequency1, frequency2, filter, gain=- 1, comments=None)¶

Sub-class of DRX specifically for Solar DRX scans. It features a reduced number of parameters needed to setup the scan.

Required Arguments:

scan target
scan intent
scan start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
scan duration (HH:MM:SS.SSS string or timedelta instance)
scan tuning frequency 1 (Hz)
scan tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

comments - comments about the scan

property fixed_body¶: Return an ephem.Body object corresponding to where the scan is pointed. None if the scan mode is TBN.

class lsl.common.idf.Jovian(target, intent, start, duration, frequency1, frequency2, filter, gain=- 1, comments=None)¶

Sub-class of DRX specifically for Jovian DRX scans. It features a reduced number of parameters needed to setup the scan.

Required Arguments:

scan target
scan intent
scan start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
scan duration (HH:MM:SS.SSS string or timedelta instance)
scan tuning frequency 1 (Hz)
scan tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

comments - comments about the scan

property fixed_body¶: Return an ephem.Body object corresponding to where the scan is pointed. None if the scan mode is TBN.

Station Meta-Data¶

Station-Level Data¶

Module for creating object oriented representations of the LWA stations.

class lsl.common.stations.ARX(id, channel=0, asp_channel=0, input='', output='')¶

Object to store information about a ARX board/channel combination. Stores ARX:

ID name (id)
Channel number (channel; 1-16)
ASP channel number (asp_channel; 1-520)
ASP rack input connector label (input)
ASP rack output connector label (output)

The object also as a functional attribute named ‘delay’ that computes the cable delay for a particular frequency or collection of frequencies in Hz.

Changed in version 1.0.0: Added attributes to hold the ASP rack input and output connector labels.

response(filter='split', dB=True)¶

Return a two-element tuple (freq in Hz, S21 magnitude in dB) for the ARX response for the current board/channel from the “ARX0026” memo on the “LWA Engineering Documents” wiki. For ARX boards at LWA-SV, data from the production tests are used.

Filter options are:

0 or ‘split’
1 or ‘full’
2 or ‘reduced’
4 or ‘split@3MHz’
5 of ‘full@3MHz’

Note

If ‘split@3MHz’ or ‘full@3MHz’ are requested for LWA1, the values for ‘split’ and ‘full’ are returned instead.

Changed in version 1.2.1: Switched the filter numbers over to match what ASP uses at LWA1 and LWA-SV. Also, changed the default filter to ‘split’ to match the default value for observations.

Changed in version 1.0.0: Add an option to specify whether the magnitude should be returned in dB or not.

class lsl.common.stations.Antenna(id, arx=None, board=0, digitizer=0, input='', stand=None, pol=0, theta=0.0, phi=0.0, fee=None, fee_port=1, cable=None, status=0)¶

Object to store the information about an antenna. Stores antenna:

ID number (id)
ARX instance the antenna is attached to (arx)
DP1/ROACH board number (board)
DP1/ROACH digitizer number (digitizer)
DP/ADP rack input connector (input)
Stand instance the antenna is part of (stand)
Polarization (0 == N-S; pol)
Antenna vertical mis-alignment in degrees (theta)
Antenna rotation mis-alignment in degrees (phi)
Fee instance the antenna is attached to (fee)
Port of the FEE used for the antenna (fee_port)
Cable instance used to connect the antenna (cable)
Status of the antenna (status)

Status codes are:

0 == Not installed
1 == Bad
2 == Suspect, possibly bad
3 == OK

Changed in version 1.0.0: Added an attribute to hold the DP rack input connector label.

property combined_status¶: Return the combined antenna + FEE status as a two digit number with the first digit representing the antenna status and the second the FEE status.

response(dB=False)¶: Return a two-element tuple (freq in Hz, mis-match efficiency) for a model LWA1 antenna from Hicks et al. (2012, PASP, 124, 1090).

New in version 1.0.0.

class lsl.common.stations.Cable(id, length, vf=0, dd=0, a0=0.00428, a1=0.0, ref_freq=10000000.0, stretch=1.0)¶

Object to store information about a cable. Stores cable:

ID name (id)
Length in meters (length)
Velocity factor (fractional, vf)
Dispersive delay (seconds, dd)
Gain term that goes as the square root of frequency (a0)
Gain term that goes as frequency (a1)
Gain term reference frequency (Hz, ref_freq)
Cable length stretch factor (stretch)
Clock offset (seconds, clock_offset)

The object also as a functional attribute named ‘delay’ that computes the cable delay for a particular frequency or collection of frequencies in Hz.

attenuation(frequency=49000000.0, dB=False)¶: Get the multiplicative cable loss for a specific frequency (in Hz). Cable loss (attenuation) affects the measured power as follows: P_out = P_in / att. If attenuations for more than one frequency are needed, the frequencies can be passed in as a numpy array.

Changed in version 1.0.0: Added the `dB’ keyword to allow dB to be returned.

delay(frequency=49000000.0, ns=False)¶: Get the delay associated with the cable in second (or nanoseconds if the ‘ns’ keyword is set to True) for a particular frequency or collection of frequencies in Hz.

gain(frequency=49000000.0, dB=False)¶: Get the cable gain (“inverse loss”) for a specific frequency (in Hz). Cable gain affects the measured power as follows: P_out = P_in * g. If gains for more than one frequency are needed, the frequencies can be passed in as a numpy array.

Changed in version 1.0.0: Added the `dB’ keyword to allow dB to be returned.

response(dB=False)¶: Return a two-element tuple (freq in Hz, attenuation) for the cable using the model from LWA Memo #170.

New in version 1.0.1.

class lsl.common.stations.FEE(id, id_number, gain1=0, gain2=0, status=0)¶

Object to store the information about a FEE. Stores FEE:

ID name (id)
ID number (id_number)
Gain of port 1 (gain1)
Gain of part 2 (gain2)
Status (status)

Status codes are:

0 == Not installed
1 == Bad
2 == Suspect, possibly bad
3 == OK

response(dB=False)¶: Return a two-element tuple (freq in Hz, gain) for the frequency- dependent gain for a v1.7 FEE from LWA Memo #190, FEE0010, Figure 3.

New in version 1.0.1.

class lsl.common.stations.LSLInterface(backend=None, mcs=None, sdf=None, metabundle=None, sdm=None)¶

Object to store information about how to work with the station in LSL. This includes names for the:

Backend module to use (backend)

MCS module to use (mcs)

SDF module to use (sdf)

Metadata module to use (metabundle)

SDM module to use (sdm)

New in version 1.2.0.

class lsl.common.stations.LWAStation(name, lat, long, elev, id='', antennas=None, interface=None)¶

Object to hold information about the a LWA station. This object can create a ephem.Observer representation of itself and identify which stands were in use at a given time. Stores station:

Name (name)

ID code (id)

Latitiude in radians [but initialized as degrees] (N is positive, lat)

Longitude in radians [but initialized as degrees] (W is negative, long)

Elevation in meters (elev)

List of Antenna instances (antennas)

LWAStation provides several method and properties for dealing with the station’s location on Earth. These include:

get_observer: Return an ephem.Observer instance representing the station

aipy_location: A tuple for setting the location of an AIPY AntennaArray
instance

geocentric_location: A tuple of the EC-EF coordinates of the station

eci_transform_matrix: Return a 3x3 transformation matrix to convert
antenna positions to ECI coordinates

eci_inverse_transform_matrix: Return a 3x3 transformation matrix to convert
antenna positions from ECI coordinates

get_enz_offset: Return the east, north, and vertical offsets to a point on
the surface of the Earth

get_pointing_and_distance: Return the pointing direction and distance to
another location on the surface of the Earth

LWAStation also provides several properties for dealing with the station’s antennas. These include:

antennas: A list of antennas

stands: A list of stands

pols: A list of polarizations

cables: A list of cables

Changed in version 1.2.0: Added a new ‘interface’ attribute which provides referenves to various modules to help interface with the station.

Changed in version 1.0.0: Converted LWAStation to be an instance of LWAStationBase and ephem.Observer to make it easier to work with ephem.Body objects.

Added additional functions for dealing with other locations.

Changed getECEFTransform() to get_eci_transform() to make the function name consistent with its purpose.

property aipy_location¶: Return a tuple that can be used by AIPY for specifying a array location.

property cables¶: Return a list of Cable instances for each antenna, sorted by digitizer number.

compute(body)¶: Update the provided ephem.Body instance with the current location as viewed from the site.

New in version 1.0.0.

property eci_inverse_transform_matrix¶: Return a 3x3 transformation matrix that converts a baseline in earth-centered inertial coordinates [x, y, z] to [east, north, elevation] for that baseline.

property eci_transform_matrix¶: Return a 3x3 transformation matrix that converts a baseline in [east, north, elevation] to earth-centered inertial coordinates for that baseline [x, y, z]. Based off the ‘local_to_eci’ function in the lwda_fits-dev library.

property geocentric_location¶: Return a tuple with earth-centered, earth-fixed coordinates for the station.

get_enz_offset(locTo)¶: Given another location on the surface of the Earth, either as a LWAStation instance or a three-element tuple of latitude (deg.), longitude (deg.), and elevation (m), return the topocentric offset in meter along the east, north, and vertical directions.

get_observer(date=None, JD=False)¶: Return a ephem.Observer object for this site.

get_pointing_and_distance(locTo)¶: Given another location on the surface of the Earth, either as a LWAStation instance or a three-element tuple of latitude (deg.), longitude (deg.), and elevation (m), return the bearing azimuth/ elevation in radians and distance in meters to the location.

Changed in version 1.0.1: Renamed from getPointingAndDirection to get_pointing_and_distance

property pols¶: Return a list of polarization (0 == N-S; 1 == E-W) for each antenna, sorted by digitizer number.

property stands¶: Return a list of Stand instances for each antenna, sorted by digitizer number.

class lsl.common.stations.Stand(id, x, y, z)¶

Object to store the information (location and ID) about a stand. Stores stand:

ID number (id)

Position relative to the center stake in meters (x,y,z)

The x, y, and z positions can also be accessed through subscripts:: Stand[0] = x Stand[1] = y Stand[2] = z

Changed in version 1.0.0: Added the option to get the positions via subscripts.

lsl.common.stations.ecef_to_geo(x, y, z)¶: Convert earth-centered, earth-fixed coordinates to (rad), longitude (rad), elevation (m) using Bowring’s method.

lsl.common.stations.geo_to_ecef(lat, lon, elev)¶: Convert latitude (rad), longitude (rad), elevation (m) to earth- centered, earth-fixed coordinates.

lsl.common.stations.get_full_stations()¶: Function to return a list of full stations.

New in version 1.2.0.

lsl.common.stations.parse_ssmif(filename)¶: Given a SSMIF file, return a fully-filled LWAStation instance. This function supports both human-readable files (filenames with ‘.txt’ extensions) or binary packed files (filenames with ‘.dat’ extensions).

Station Dynamic MIB Data¶

Module for reading in an interpreting binary-packed Station Dynamic MIB (SDM) files (as defined in MCS0031, v5).

class lsl.common.sdm.SDM(station=None, shl=None, asp=None, dp=None, dr=None, status=None, ant_status=None, dpo_status=None, settings=None)¶

Python object that holds the various bits of information in a binary-packed Station Dynamic MIB file (SDM file).

update_antennas(antennas)¶: Given a list of lsl.common.stations.Antenna instances, return a new list of Antenna instances with updated antenna status codes.

class lsl.common.sdm.SubSubSystemStatus(fee=None, rpd=None, sep=None, arb=None, dp1=None, dp2=None, dr=None)¶

Python object that holds the status for the sub-subsystems in a SDM file.

binary_read(fh)¶: Given an open file handle, interpret it in the context of a subsubsystem_status_struct C structure and update the Python instance accordingly.

class lsl.common.sdm.SubSystemStatus(name, summary=6, info='UNK', time=0)¶

Python object that holds the status for a particular subsystem in a SDM file.

binary_read(fh)¶: Given an open file handle, interpret it in the context of a subsystem_status_struct C structure and update the Python instance accordingly.

lsl.common.sdm.parse_sdm(filename)¶: Given a filename, read the file’s contents into the SDM instance and return that instance.

Stand-Level Data¶

This module stores various functions that are needed for computing UV coverage and time delays. The functions in the module:

compute the u, v, and w coordinates of all baselines defined by an array of stands

compute the track through the uv-plane of a collection of baselines as the Earth rotates.

Changed in version 0.4.0: Removed function for dealing with meta-data (position, cable length, etc.) for individual stands since these are wrapped in the new lsl.common.stations module.

Changed in version 1.0.0: Generalized the compute_uvw() and compute_uv_track() functions.

Changed in version 2.0.1: Added support for ephem.Angle, astropy.coordinates.Angle, and astropy.coordinates.EarthLocation instances in the compute_uvw() and compute_uv_track() functions.

Session and Observation Specification for a Single LWA Station¶

DP-Based Stations¶

Module that contains all of the relevant class to build up a representation of a session definition file as defined in MCS0030v5. The hierarchy of classes is:

Project - class that holds all of the information about the project (including
the observer) and one or more sessions. Technically, a SD file has only one session but this approach allows for the generation of multiple SD files from a single Project object.

Observer - class that hold the observer’s name and numeric ID

Session - class that holds all of the observations associated with a particular
DP output.

Observations - class that hold information about a particular observation. It
includes a variety of attributes that are used to convert human- readable inputs to SDF data values. The observation class is further subclasses into:

TBW - class for TBW observations

TBN - class for TBN observations

DRX - class for general DRX observation, with sub-classes: * Solar - class for solar tracking * Jovian - class for Jovian tracking

Stepped - class for stepped observations

BeamStep - class that holds the information about a particular step in a Stepped
Observation

All of the classes, except for Stepped and BeamStep, are complete and functional. In addition, most class contain ‘validate’ attribute functions that can be used to determine if the project/session/observation are valid or not given the constraints of the DP system.

In addition to providing the means for creating session definition files from scratch, this module also includes a simple parser for SD files.

Changed in version 2.0.0: Added support for astropy.time.Time and astropy.coordinates.Angle instances

Changed in version 1.0.0: Added the get_observation_start_stop() function. Renamed parse_timeString() to parse_time() parse_time() can now accept dates/times as timezone-aware datetime instances Observations can now be initialized with durations as timedelta instances Observations can now be initialized with RA/dec/az/alt as ephem.hours and ephem.degrees instances

class lsl.common.sdf.BeamStep(c1, c2, duration, frequency1, frequency2, is_radec=True, max_snr=False, spec_delays=None, spec_gains=None)¶

Class for holding all of the information (pointing center, tuning frequencies, etc.)associated with a particular step.

Required Keywords:

pointing coordinate 1 (RA [hours] or azimuth [degrees] or ephem.hours/ephem.degrees instance)
pointing coordinate 2 (dec or elevation/altitude [degrees] or ephem.degrees instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)

Optional Keywords:

is_radec - whether the coordinates are in RA/Dec or Az/El pairs (default=RA/Dec)
max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
spec_delays - 520 list of delays to apply for each antenna
spec_gains - 260 by 2 by 2 list of gains ([[XY, XY], [YX, YY]]) to apply for each antenna

Note

If spec_delays is specified, spec_gains must also be specified. Specifying both spec_delays and spec_gains overrides the max_snr keyword.

Changed in version 1.0.0: Added support for azimuth/altitude and RA/dec values as ephem.hours/ephem.degrees instances

property c1¶: Coordinate 1 - hours (J2000) if RA, degrees if azimuth.

property c2¶: Coordinate 2 - degrees (J2000) if dec., degrees if elevation.

property duration¶: Duration in seconds.

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is either TBN or TBW.

property frequency1¶: Tuning 1 frequency in Hz.

property frequency2¶: Tuning 2 frequency in Hz.

get_beam_type()¶: Return a valid value for beam type based on whether maximum S/N beam forming has been requested.

update()¶: Update the settings.

validate(verbose=False)¶: Evaluate the step and return True if it is valid, False otherwise.

class lsl.common.sdf.DRX(name, target, start, duration, ra, dec, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Sub-class of Observation specifically for DRX-style observations.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation RA in hours, J2000.0 or ephem.hours instance
observation Dec in degrees, J2000.0 or ephem.hours instance
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
comments - comments about the observation

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For DRX:

bytes = duration * sample_rate / 4096 * 4128 bytes * 2 tunings * 2 pols.

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is an all-sky mode.

set_beamdipole_mode(stand, beam_gain=0.04, dipole_gain=1.0, pol='X')¶

Convert the current observation to a ‘beam-dipole mode’ observation with the specified stand. Setting the stand to zero will disable the ‘beam-dipole mode’ for this observation’.

Keywords:

beam_gain - BAM gain to use for each dipole in the beam
default: 0.04; range: 0.0 to 1.0
dipole_gain - BAM gain to use for the single dipole
default: 1.0; range: 0.0 to 1.0
pol - Polarization to record default: “X”

property target_visibility¶: Return the fractional visibility of the target during the observation period.

validate(verbose=False)¶: Evaluate the observation and return True if it is valid, False otherwise.

class lsl.common.sdf.Jovian(name, target, start, duration, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Sub-class of DRX specifically for Jovian DRX observations. It features a reduced number of parameters needed to setup the observation.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
comments - comments about the observation

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is either TBN or TBW.

class lsl.common.sdf.Observation(name, target, start, duration, mode, ra, dec, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Class to hold the specifics of an observations. It currently handles TBW, TBN, TRK_RADEC, TRK_SOL, TRK_JOV, and Stepped

Changed in version 1.0.0: Added support for RA/dec values as ephem.hours/ephem.degrees instances

property dec¶: Target dec. (J2000).

property duration¶: Duration in seconds.

estimate_bytes()¶: Place holder for functions that return the estimate size of the data set being defined by the observation.

property fixed_body¶: Place holder for functions that return ephem.Body objects (or None) that define the pointing center of the observation.

property frequency1¶: Tuning 1 frequency in Hz.

property frequency2¶: Tuning 2 frequency in Hz.

get_beam_type()¶: Return a valid value for beam type based on whether maximum S/N beam forming has been requested.

property ra¶: Target RA (J2000).

property start¶: Start time.

property target_visibility¶: Place holder for functions that return the fractional visibility of the target during the observation period.

update()¶: Update the computed parameters from the string values.

validate(verbose=False)¶: Place holder for functions that evaluate the observation and return True if it is valid, False otherwise.

class lsl.common.sdf.Observer(name, id, first=None, last=None)¶: Class to hold information about an observer.

class lsl.common.sdf.Project(observer, name, id, sessions=None, comments=None, project_office=None)¶

Class to hold all the information about a specific session for a project/proposal.

Changed in version 1.2.1: Added a new writeto() method to directly write the SDF to a file.

append(newSession)¶: Add a new Session to the list of sessions.

render(session=0, verbose=False)¶: Create a session definition file that corresponds to the specified session. Returns the SD file’s contents as a string.

update()¶: Update the various sessions that are part of this project.

validate(verbose=False)¶: Examine all of the sessions and all of their observations to check for validity. If everything is valid, return True. Otherwise, return False.

writeto(filename, session=0, verbose=False, overwrite=False)¶: Create a session definition file that corresponds to the specified session and write it to the provided filename.

class lsl.common.sdf.ProjectOffice(project=None, sessions=None, observations=None)¶: Class to hold comments from the LWA object office. This class isn’t really needed to create SD files, but it is helpful for parsing SD files.

class lsl.common.sdf.Session(name, id, observations=None, data_return_method='DRSU', comments=None, station=<LWAStation id='VL', name='LWA1', lat=34:04:08.0, long=-107:37:42.1, elev=2133.6, pressure=0.0, horizon=0:00:00.0, antennas=[...], interface=<LSLInterface backend='lsl.common.dp', mcs='lsl.common.mcs', sdf='lsl.common.sdf', metabundle='lsl.common.metabundle', sdm='lsl.common.sdm'>>)¶

Class to hold all of the observations in a session.

append(newObservation)¶: Add a new Observation to the list of observations.

set_mib_record_interval(component, interval)¶

Set the record interval for one of the level-1 subsystems (ASP, DP_, etc.) to a particular value in minutes. A KeyError is raised if an invalid sub-system is specified.

Special Values are:

-1 = use the MCS default interval
0 = never record the MIB entries (the entries are still updated, however)

set_mib_update_interval(component, interval)¶

Set the update interval for one of the level-1 subsystems (ASP, DP_, etc.) to a particular value in minutes. A KeyError is raised if an invalid sub-system is specified.

Special Values are:

-1 = use the MCS default interval
0 = request no updates to the MIB entries

property spectrometer_channels¶: Number of spectrometer channesl to output, 0 is disables.

property spectrometer_integration¶: Number of FFT windows per spectrometer integration, 0 to disable.

property spectrometer_metatag¶: Spectrometer polarization selection.

update()¶: Update the various observations in the session.

validate(verbose=False)¶: Examine all of the observations associated with the session to check for validity. If everything is valid, return True. Otherwise, return False.

class lsl.common.sdf.Solar(name, target, start, duration, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Sub-class of DRX specifically for Solar DRX observations. It features a reduced number of parameters needed to setup the observation.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
comments - comments about the observation

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is either TBN or TBW.

class lsl.common.sdf.Stepped(name, target, start, filter, steps=None, is_radec=True, gain=- 1, comments=None)¶

Sub-class of Observation for dealing with STEPPED-mode observations. It features a reduced number of parameters needed to setup the observation and added support for the individual steps.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
integer filter code

Optional Keywords:

steps - array of BeamStep objects that specify the different steps
comments - comments about the observation

append(newStep)¶: Add a new BeamStep step to the list of steps.

property duration¶: Parse the list of BeamStep objects to get the total observation duration as the number of seconds in that period.

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For DRX:

bytes = duration * sample_rate / 4096 * 4128 bytes * 2 tunings * 2 pols.

set_beamdipole_mode(stand, beam_gain=0.04, dipole_gain=1.0, pol='X')¶

Convert the current observation to a ‘beam-dipole mode’ observation with the specified stand. Setting the stand to zero will disable the ‘beam-dipole mode’ for this observation’.

Keywords:

beam_gain - BAM gain to use for each dipole in the beam
default: 0.04; range: 0.0 to 1.0
dipole_gain - BAM gain to use for the single dipole
default: 1.0; range: 0.0 to 1.0
pol - Polarization to record default: “X”

property target_visibility¶: Return the fractional visibility of the target during the observation period.

update()¶: Update the computed parameters from the string values.

validate(verbose=False)¶: Evaluate the observation and return True if it is valid, False otherwise.

class lsl.common.sdf.TBN(name, target, start, duration, frequency, filter, gain=- 1, comments=None)¶

Sub-class of Observation specifically for TBN observations. It features a reduced number of parameters needed to setup the observation.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation frequency (Hz)
integer filter code

Optional Keywords:

comments - comments about the observation

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For TBN:

bytes = duration * sample_rate / 512 * 1048 bytes * 260 stands * 2 pols.

validate(verbose=False)¶

Evaluate the observation and return True if it is valid, False otherwise.

..note::: This version of sdf allows for TBN tuning between 5 and 93 MHz.

class lsl.common.sdf.TBW(name, target, start, samples, bits=12, comments=None)¶

Sub-class of Observation specifically for TBW observations. It features a reduced number of parameters needed to setup the observation and provides extra information about the number of data bits and the number of samples.

Note

TBW read-out times in ms are calculated using (samples/196000+1)*5000 per MCS

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string)
integer number of samples

Optional Keywords:

bits - number of data bits (4 or 12)
comments - comments about the observation

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For TBW:

bytes = samples / samplesPerFrame * 1224 bytes * 260 stands

validate(verbose=False)¶: Evaluate the observation and return True if it is valid, False otherwise.

lsl.common.sdf.get_observation_start_stop(obs)¶: Given an observation, get the start and stop times (returned as a two- element tuple of UTC datetime instances).

New in version 1.0.0.

lsl.common.sdf.is_valid(filename, verbose=False)¶: Given a filename, see if it is valid SDF file or not.

New in version 1.2.0.

lsl.common.sdf.parse_sdf(filename, verbose=False)¶: Given a filename, read the file’s contents into the SDM instance and return that instance.

ADP-Based Stations¶

Module that contains all of the relevant class to build up a representation of a session definition file as defined in MCS0030v5 and updated for LWA-SV. The hierarchy of classes is:

Project - class that holds all of the information about the project (including
the observer) and one or more sessions. Technically, a SD file has only one session but this approach allows for the generation of multiple SD files from a single Project object.

Observer - class that hold the observer’s name and numeric ID

Session - class that holds all of the observations associated with a particular
ADP output.

Observations - class that hold information about a particular observation. It
includes a variety of attributes that are used to convert human- readable inputs to SDF data values. The observation class is further subclasses into:

TBF - class for TBF observations

TBN - class for TBN observations

DRX - class for general DRX observation, with sub-classes: * Solar - class for solar tracking * Jovian - class for Jovian tracking

Stepped - class for stepped observations

BeamStep - class that holds the information about a particular step in a Stepped
Observation

All of the classes, except for Stepped and BeamStep, are complete and functional. In addition, most class contain ‘validate’ attribute functions that can be used to determine if the project/session/observation are valid or not given the constraints of the ADP system.

In addition to providing the means for creating session definition files from scratch, this module also includes a simple parser for SD files.

Changed in version 2.0.0: Added support for astropy.time.Time and astropy.coordinates.Angle instances

Changed in version 1.0.0: Added the get_observation_start_stop() function. Renamed parse_timeString() to parse_time() parse_time() can now accept dates/times as timezone-aware datetime instances Observations can now be initialized with durations as timedelta instances Observations can now be initialized with RA/dec/az/alt as ephem.hours and ephem.degrees instances

class lsl.common.sdfADP.BeamStep(c1, c2, duration, frequency1, frequency2, is_radec=True, max_snr=False, spec_delays=None, spec_gains=None)¶

Class for holding all of the information (pointing center, tuning frequencies, etc.)associated with a particular step.

Required Keywords:

pointing coordinate 1 (RA [hours] or azimuth [degrees] or ephem.hours/ephem.degrees instance)
pointing coordinate 2 (dec or elevation/altitude [degrees] or ephem.degrees instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)

Optional Keywords:

is_radec - whether the coordinates are in RA/Dec or Az/El pairs (default=RA/Dec)
max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
spec_delays - 520 list of delays to apply for each antenna
spec_gains - 260 by 2 by 2 list of gains ([[XY, XY], [YX, YY]]) to apply for each antenna

Note

If spec_delays is specified, spec_gains must also be specified. Specifying both spec_delays and spec_gains overrides the max_snr keyword.

Changed in version 1.0.0: Added support for azimuth/altitude and RA/dec values as ephem.hours/ephem.degrees instances

property c1¶: Coordinate 1 - hours (J2000) if RA, degrees if azimuth.

property c2¶: Coordinate 2 - degrees (J2000) if dec., degrees if elevation.

property duration¶: Duration in seconds.

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is either TBN or TBW.

property frequency1¶: Tuning 1 frequency in Hz.

property frequency2¶: Tuning 2 frequency in Hz.

get_beam_type()¶: Return a valid value for beam type based on whether maximum S/N beam forming has been requested.

update()¶: Update the settings.

validate(verbose=False)¶: Evaluate the step and return True if it is valid, False otherwise.

class lsl.common.sdfADP.DRX(name, target, start, duration, ra, dec, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Sub-class of Observation specifically for DRX-style observations.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation RA in hours, J2000.0 or ephem.hours instance
observation Dec in degrees, J2000.0 or ephem.hours instance
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
comments - comments about the observation

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For DRX:

bytes = duration * sample_rate / 4096 * 4128 bytes * 2 tunings * 2 pols.

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is an all-sky mode.

set_beamdipole_mode(stand, beam_gain=0.04, dipole_gain=1.0, pol='X')¶

Convert the current observation to a ‘beam-dipole mode’ observation with the specified stand. Setting the stand to zero will disable the ‘beam-dipole mode’ for this observation’.

Keywords:

beam_gain - BAM gain to use for each dipole in the beam
default: 0.04; range: 0.0 to 1.0
dipole_gain - BAM gain to use for the single dipole
default: 1.0; range: 0.0 to 1.0
pol - Polarization to record default: “X”

property target_visibility¶: Return the fractional visibility of the target during the observation period.

validate(verbose=False)¶: Evaluate the observation and return True if it is valid, False otherwise.

class lsl.common.sdfADP.Jovian(name, target, start, duration, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Sub-class of DRX specifically for Jovian DRX observations. It features a reduced number of parameters needed to setup the observation.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
comments - comments about the observation

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is either TBN or TBW.

class lsl.common.sdfADP.Observation(name, target, start, duration, mode, ra, dec, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Class to hold the specifics of an observations. It currently handles TBW, TBN, TRK_RADEC, TRK_SOL, TRK_JOV, and Stepped

Changed in version 1.0.0: Added support for RA/dec values as ephem.hours/ephem.degrees instances

property dec¶: Target dec. (J2000).

property duration¶: Duration in seconds.

estimate_bytes()¶: Place holder for functions that return the estimate size of the data set being defined by the observation.

property fixed_body¶: Place holder for functions that return ephem.Body objects (or None) that define the pointing center of the observation.

property frequency1¶: Tuning 1 frequency in Hz.

property frequency2¶: Tuning 2 frequency in Hz.

get_beam_type()¶: Return a valid value for beam type based on whether maximum S/N beam forming has been requested.

property ra¶: Target RA (J2000).

property start¶: Start time.

property target_visibility¶: Place holder for functions that return the fractional visibility of the target during the observation period.

update()¶: Update the computed parameters from the string values.

validate(verbose=False)¶: Place holder for functions that evaluate the observation and return True if it is valid, False otherwise.

class lsl.common.sdfADP.Observer(name, id, first=None, last=None)¶: Class to hold information about an observer.

class lsl.common.sdfADP.Project(observer, name, id, sessions=None, comments=None, project_office=None)¶

Class to hold all the information about a specific session for a project/proposal.

Changed in version 1.2.1: Added a new writeto() method to directly write the SDF to a file.

render(session=0, verbose=False)¶: Create a session definition file that corresponds to the specified session. Returns the SD file’s contents as a string.

class lsl.common.sdfADP.ProjectOffice(project=None, sessions=None, observations=None)¶: Class to hold comments from the LWA object office. This class isn’t really needed to create SD files, but it is helpful for parsing SD files.

class lsl.common.sdfADP.Session(name, id, observations=None, data_return_method='DRSU', comments=None, station=<LWAStation id='SV', name='LWASV', lat=34:20:54.1, long=-106:53:08.8, elev=1477.8, pressure=0.0, horizon=0:00:00.0, antennas=[...], interface=<LSLInterface backend='lsl.common.adp', mcs='lsl.common.mcsADP', sdf='lsl.common.sdfADP', metabundle='lsl.common.metabundleADP', sdm='lsl.common.sdmADP'>>)¶

Class to hold all of the observations in a session.

validate(verbose=False)¶: Examine all of the observations associated with the session to check for validity. If everything is valid, return True. Otherwise, return False.

class lsl.common.sdfADP.Solar(name, target, start, duration, frequency1, frequency2, filter, gain=- 1, max_snr=False, comments=None)¶

Sub-class of DRX specifically for Solar DRX observations. It features a reduced number of parameters needed to setup the observation.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation tuning frequency 1 (Hz)
observation tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

max_snr - specifies if maximum signal-to-noise beam forming is to be used
(default = False)
comments - comments about the observation

property fixed_body¶: Return an ephem.Body object corresponding to where the observation is pointed. None if the observation mode is either TBN or TBW.

class lsl.common.sdfADP.Stepped(name, target, start, filter, steps=None, is_radec=True, gain=- 1, comments=None)¶

Sub-class of Observation for dealing with STEPPED-mode observations. It features a reduced number of parameters needed to setup the observation and added support for the individual steps.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
integer filter code

Optional Keywords:

steps - array of BeamStep objects that specify the different steps
comments - comments about the observation

append(newStep)¶: Add a new BeamStep step to the list of steps.

property duration¶: Parse the list of BeamStep objects to get the total observation duration as the number of seconds in that period.

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For DRX:

bytes = duration * sample_rate / 4096 * 4128 bytes * 2 tunings * 2 pols.

set_beamdipole_mode(stand, beam_gain=0.04, dipole_gain=1.0, pol='X')¶

Convert the current observation to a ‘beam-dipole mode’ observation with the specified stand. Setting the stand to zero will disable the ‘beam-dipole mode’ for this observation’.

Keywords:

beam_gain - BAM gain to use for each dipole in the beam
default: 0.04; range: 0.0 to 1.0
dipole_gain - BAM gain to use for the single dipole
default: 1.0; range: 0.0 to 1.0
pol - Polarization to record default: “X”

property target_visibility¶: Return the fractional visibility of the target during the observation period.

update()¶: Update the computed parameters from the string values.

validate(verbose=False)¶: Evaluate the observation and return True if it is valid, False otherwise.

class lsl.common.sdfADP.TBF(name, target, start, frequency1, frequency2, filter, samples, comments=None)¶

Sub-class of Observation specifically for TBF observations. It features a reduced number of parameters needed to setup the observation and provides extra information about the number of number of samples.

Note

TBF read-out times in ms are calculated using (samples / 196000 + 1) * 150 per MCS

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string)
observation frequency (Hz) - 1
observation frequency (Hz) - 2
integer filter code
integer number of samples

Optional Keywords:

comments - comments about the observation

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For TBF:

bytes = samples / samplesPerFrame * 1224 bytes

update()¶: Update the computed parameters from the string values.

validate(verbose=False)¶: Evaluate the observation and return True if it is valid, False otherwise.

class lsl.common.sdfADP.TBN(name, target, start, duration, frequency, filter, gain=- 1, comments=None)¶

Sub-class of Observation specifically for TBN observations. It features a reduced number of parameters needed to setup the observation.

Required Arguments:

observation name
observation target
observation start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
observation duration (HH:MM:SS.SSS string or timedelta instance)
observation frequency (Hz)
integer filter code

Optional Keywords:

comments - comments about the observation

estimate_bytes()¶: Estimate the data volume for the specified type and duration of observations. For TBN:

bytes = duration * sample_rate / 512 * 1048 bytes * 260 stands * 2 pols.

validate(verbose=False)¶

Evaluate the observation and return True if it is valid, False otherwise.

..note::: This version of sdf allows for TBN tuning between 5 and 93 MHz.

lsl.common.sdfADP.get_observation_start_stop(obs)¶: Given an observation, get the start and stop times (returned as a two- element tuple of UTC datetime instances).

New in version 1.0.0.

lsl.common.sdfADP.is_valid(filename, verbose=False)¶: Given a filename, see if it is valid SDF file or not.

New in version 1.2.0.

lsl.common.sdfADP.parse_sdf(filename, verbose=False)¶: Given a filename, read the file’s contents into the SDM instance and return that instance.

Run and Scan Specification for the LWA Swarm¶

Module that contains all of the relevant class to build up a representation of a interferometer definition file. The hierarchy of classes is:

Project - class that holds all of the information about the project (including
the observer) and one or more runs. Technically, a ID file has only one run but this approach allows for the generation of multiple SD files from a single Project object.

Observer - class that hold the observer’s name and numeric ID

Run - class that holds all of the scans associated and the associated
correlator setup for a with a particular interferometer run

Scan - class that hold information about a particular scan. It
includes a variety of attributes that are used to convert human- readable inputs to SDF data values. The scan class is further subclasses into:

DRX - class for general DRX scan, with sub-classes: * Solar - class for solar tracking * Jovian - class for Jovian tracking

Most class contain ‘validate’ attribute functions that can be used to determine if the project/run/scan are valid or not given the constraints of the ADP system.

In addition to providing the means for creating interferometer definition files from scratch, this module also includes a simple parser for ID files.

Changed in version 2.0.0: Added support for astropy.time.Time and astropy.coordinates.Angle instances

New in version 1.2.4.

class lsl.common.idf.DRX(target, intent, start, duration, ra, dec, frequency1, frequency2, filter, gain=- 1, pm=[0.0, 0.0], comments=None)¶

Required Arguments:

scan target
scan intent
scan start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
scan duration (HH:MM:SS.SSS string or timedelta instance)
scan RA in hours, J2000.0 or ephem.hours instance
scan Dec in degrees, J2000.0 or ephem.hours instance
scan tuning frequency 1 (Hz)
scan tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

comments - comments about the scan

class lsl.common.idf.Jovian(target, intent, start, duration, frequency1, frequency2, filter, gain=- 1, comments=None)¶

Sub-class of DRX specifically for Jovian DRX scans. It features a reduced number of parameters needed to setup the scan.

Required Arguments:

scan target
scan intent
scan start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
scan duration (HH:MM:SS.SSS string or timedelta instance)
scan tuning frequency 1 (Hz)
scan tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

comments - comments about the scan

property fixed_body¶: Return an ephem.Body object corresponding to where the scan is pointed. None if the scan mode is TBN.

class lsl.common.idf.Observer(name, id, first=None, last=None)¶: Class to hold information about an observer.

class lsl.common.idf.Project(observer, name, id, runs=None, comments=None, project_office=None)¶

Class to hold all the information about a specific interferometer run for a project/proposal.

append(newRun)¶: Add a new run to the list of runs.

generate_sdfs(starting_session_id=1, run=0, verbose=False)¶: Convert the ID file into a collection of lsl.common.sdfADP.Project instances that can be used to write SD files.

render(run=0, verbose=False)¶: Create a run definition file that corresponds to the specified run. Returns the ID file’s contents as a string.

update()¶: Update the various runs that are part of this project.

validate(verbose=False)¶: Examine all of the runs and all of their scans to check for validity. If everything is valid, return True. Otherwise, return False.

writeto(filename, run=0, verbose=False, overwrite=False)¶: Create a run definition file that corresponds to the specified run and write it to the provided filename.

class lsl.common.idf.ProjectOffice(project=None, runs=None, scans=None)¶: Class to hold comments from the LWA object office. This class isn’t really needed to create ID files, but it is helpful for parsing ID files.

class lsl.common.idf.Run(name, id, scans=None, data_return_method='DRSU', comments=None, correlator_channels=512, correlator_inttime=1.0, correlator_basis='linear', stations=[<LWAStation id='VL', name='LWA1', lat=34:04:08.0, long=-107:37:42.1, elev=2133.6, pressure=0.0, horizon=0:00:00.0, antennas=[...], interface=<LSLInterface backend='lsl.common.dp', mcs='lsl.common.mcs', sdf='lsl.common.sdf', metabundle='lsl.common.metabundle', sdm='lsl.common.sdm'>>, <LWAStation id='SV', name='LWASV', lat=34:20:54.1, long=-106:53:08.8, elev=1477.8, pressure=0.0, horizon=0:00:00.0, antennas=[...], interface=<LSLInterface backend='lsl.common.adp', mcs='lsl.common.mcsADP', sdf='lsl.common.sdfADP', metabundle='lsl.common.metabundleADP', sdm='lsl.common.sdmADP'>>])¶

Class to hold all of the scans in an interferometer run.

append(newScan)¶: Add a new Scan to the list of scans.

property correlator_basis¶: Correlator output polarization basis.

property correlator_channels¶: Number of correlator channels to use.

property correlator_inttime¶: Correlator integration time in seconds.

property stations¶: List of LWA stations to use in the interferometer.

update()¶: Update the various scans in the run.

validate(verbose=False)¶: Examine all of the scans associated with the run to check for validity. If everything is valid, return True. Otherwise, return False.

class lsl.common.idf.Scan(target, intent, start, duration, mode, ra, dec, frequency1, frequency2, filter, gain=- 1, pm=[0.0, 0.0], comments=None)¶

Class to hold the specifics of a scans. It currently handles TRK_RADEC, TRK_SOL, and TRK_JOV.

add_alt_phase_center(target_or_apc, intent=None, ra=None, dec=None, pm=None)¶: Add an alternate phase center to the scan.

property dec¶: Target dec. (J2000).

property duration¶: Duration in seconds.

estimate_bytes()¶: Estimate the data volume for the specified type and duration of scans. For DRX:

bytes = duration * sample_rate / 4096 * 4128 bytes * 2 tunings * 2 pols.

property fixed_body¶: Return an ephem.Body object corresponding to where the scan is pointed. None if the scan mode is TBN.

property frequency1¶: Tuning 1 frequency in Hz.

property frequency2¶: Tuning 2 frequency in Hz.

property intent¶: Obsevational intent.

property pm¶: Target proper motion in mas/yr.

property ra¶: Target RA (J2000).

property start¶: Start time.

property target_visibility¶: Return the fractional visibility of the target during the scan period.

update()¶: Update the computed parameters from the string values.

validate(verbose=False)¶: Evaluate the scan and return True if it is valid, False otherwise.

class lsl.common.idf.Solar(target, intent, start, duration, frequency1, frequency2, filter, gain=- 1, comments=None)¶

Sub-class of DRX specifically for Solar DRX scans. It features a reduced number of parameters needed to setup the scan.

Required Arguments:

scan target
scan intent
scan start date/time (UTC YYYY/MM/DD HH:MM:SS.SSS string or timezone- aware datetime instance)
scan duration (HH:MM:SS.SSS string or timedelta instance)
scan tuning frequency 1 (Hz)
scan tuning frequency 1 (Hz)
integer filter code

Optional Keywords:

comments - comments about the scan

property fixed_body¶: Return an ephem.Body object corresponding to where the scan is pointed. None if the scan mode is TBN.

lsl.common.idf.get_scan_start_stop(obs)¶: Given a scan, get the start and stop times (returned as a two- element tuple of UTC datetime instances).

lsl.common.idf.is_valid(filename, verbose=False)¶: Given a filename, see if it is valid IDF file or not.

lsl.common.idf.parse_idf(filename, verbose=False)¶: Given a filename, read the file’s contents into the IDF instance and return that instance.

Data Readers¶

LSL Developer Primitives¶

LWA Development Primitives - A set of utilities that should make developing new analysis software easier. These functions wrap the nitty gritty of the file reading and unpacking behind Python objects.

Data format objects included are:

TBWFile
TBNFile
DRXFile
DRSpecFile
TBFFile
CORFILE

Also included are the LWA1DataFile, LWASVDataFile, and LWADataFile functions that take a filename and try to determine the correct data format object to use.

Changed in version 1.2.0: Added support for LWA-SV ADP data

class lsl.reader.ldp.DRSpecFile(filename=None, fh=None, ignore_timetag_errors=False, buffering=- 1)¶

Class to make it easy to interface with a DR Spectrometer file. Methods defined for this class are:

get_info - Get information about the file’s contents

get_remaining_frame_count - Get the number of frames remaining in the file

offset - Offset a specified number of seconds into the file

read_frame - 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, time_in_samples=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.

The time tag is returned as seconds since the UNIX epoch as a lsl.reader.base.FrameTimestamp instance by default. However, the time tags can be returns as samples at lsl.common.dp.fS if the `time_in_samples’ keyword is set.

..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.

read_frame()¶: Read and return a single lsl.reader.drspec.Frame instance.

class lsl.reader.ldp.DRXFile(filename=None, fh=None, ignore_timetag_errors=False, buffering=- 1)¶

Class to make it easy to interface with a DRX file. Methods defined for this class are:

get_info - Get information about the file’s contents
get_remaining_frame_count - Get the number of frames remaining in the file
offset - Offset a specified number of seconds into the file
read_frame - Read and return a single lsl.reader.drx.Frame instance
read - Read a chunk of data in and return it as a numpy array
estimate_levels - Estimate the n-sigma level for the absolute value of the voltages

estimate_levels(nframe=100, sigma=5.0)¶

Estimate the n-sigma level for the absolute value of the voltages. Returns a list with indicies corresponding to:

Tuning 1, X pol.

Tuning 1, Y pol.

Tuning 2, X pol.

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, time_in_samples=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.

The time tag is returned as seconds since the UNIX epoch as a lsl.reader.base.FrameTimestamp instance by default. However, the time tags can be returns as samples at lsl.common.dp.fS if the `time_in_samples’ keyword is set.

..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

read_frame()¶: Read and return a single lsl.reader.drx.Frame instance.

lsl.reader.ldp.LWA1DataFile(filename=None, fh=None, ignore_timetag_errors=False, buffering=- 1)¶: 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.LWADataFile(filename=None, fh=None, ignore_timetag_errors=False, buffering=- 1)¶: Wrapper around the various 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, ignore_timetag_errors=False, buffering=- 1)¶: 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.

class lsl.reader.ldp.TBFFile(filename=None, fh=None, ignore_timetag_errors=False, buffering=- 1)¶

Class to make it easy to interface with a TBF file. Methods defined for this class are:

get_info - Get information about the file’s contents
get_remaining_frame_count - Get the number of frames remaining in the file
offset - Offset a specified number of seconds into the file
read_frame - 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, time_in_samples=False)¶

Read and return the entire TBF capture. This function returns a three-element tuple with elements of:

the actual duration of data read in,

the time tag for the first sample, and

a 3-D Numpy array of data.

The time tag is returned as seconds since the UNIX epoch as a lsl.reader.base.FrameTimestamp instance by default. However, the time tags can be returns as samples at lsl.common.dp.fS if the `time_in_samples’ keyword is set.

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

read_frame()¶: Read and return a single lsl.reader.tbf.Frame instance.

class lsl.reader.ldp.TBNFile(filename=None, fh=None, ignore_timetag_errors=False, buffering=- 1)¶

Class to make it easy to interface with a TBN file. Methods defined for this class are:

get_info - Get information about the file’s contents
get_remaining_frame_count - Get the number of frames remaining in the file
offset - Offset a specified number of seconds into the file
read_frame - Read and return a single lsl.reader.tbn.Frame instance
read - Read a chunk of data in and return it as a numpy array
estimate_levels - Estimate the n-sigma level for the absolute value of the voltages

estimate_levels(nframe=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, time_in_samples=False)¶

Read in a chunk (in seconds) of TBN data. This function returns a three-element tuple with elements of:

the actual duration of data read in,

the time tag for the first sample, and

a 2-D Numpy array of data.

The time tag is returned as seconds since the UNIX epoch as a lsl.reader.base.FrameTimestamp instance by default. However, the time tags can be returns as samples at lsl.common.dp.fS if the `time_in_samples’ keyword is set.

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

read_frame()¶: Read and return a single lsl.reader.tbn.Frame instance.

class lsl.reader.ldp.TBWFile(filename=None, fh=None, ignore_timetag_errors=False, buffering=- 1)¶

Class to make it easy to interface with a TBW file. Methods defined for this class are:

get_info - Get information about the file’s contents
get_remaining_frame_count - Get the number of frames remaining in the file
read_frame - 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, time_in_samples=False)¶

Read and return the entire TBW capture. This function returns a three-element tuple with elements of:

the actual duration of data read in,

the time tag for the first sample, and

a 2-D Numpy array of data.

The time tag is returned as seconds since the UNIX epoch as a lsl.reader.base.FrameTimestamp instance by default. However, the time tags can be returns as samples at lsl.common.dp.fS if the `time_in_samples’ 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.

read_frame()¶: Read and return a single lsl.reader.tbw.Frame instance.

Python module that contains various helpers for the lsl.reader module.

New in version 2.0.0.

class lsl.reader.utils.FilePositionSaver(fh)¶: Simple class to save the current location in a file and return to that position when we are done with it.

class lsl.reader.utils.SplitFileWrapper(filenames, sort=True, buffering=- 1)¶: Class to allow seamless access to a file that has been split into parts.

class lsl.reader.base.FrameTimestamp(si=0, sf=0.0)¶

Class to represent the UNIX timestamp of a data frame as an integer number of seconds and a fractional number of seconds.

property astropy¶: Timestamp as an astropy.time.Time instance.

property datetime¶: Timestamp as a naive datetime.datetime instance in UTC.

property dp_timetag¶: Timestamp as a DP timetag (ticks of a 196 MHz clock since UTC midnight on January 1, 1970).

classmethod from_dp_timetag(value, offset=0)¶: Create a new FrameTimestamp instance from a raw DP timetag with an optional offset.

classmethod from_mjd_mpm(mjd, mpm)¶: Create a new FrameTimestamp from a MJD/MPM (milliseconds past midnight) pair.

classmethod from_pulsar_mjd(mjd, mjd_frac, sec_frac)¶: Create a new FrameTimstamp from a three-element tuple of integer number of MJD days, fractional MJD day, and fractional seconds.

property jd¶: JD as a floating point value.

property mjd¶: MJD as a floating point value.

property pulsar_mjd¶: MJD as three-element tuple of integer number of MJD days, fractional MJD day, and fractional seconds.

property unix¶: UNIX timestamp as a floating point value.

property utc_datetime¶: Timestamp as a time zone-aware datetime instance in UTC.

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

FramePayload - 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:

convert a frame in a file to a Frame object and
describe the format of the data in the file.

For reading in data, use the read_frame function. It takes a python file- handle as an input and returns a fully-filled Frame object. read_frame 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:

get_data_bits: read in the first frame of an open file handle and return whether or not the data is 12 or 4-bit
get_frames_per_obs: 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.Frame(header=None, payload=None, valid=True)¶

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

property data_bits¶: Convenience wrapper for the Frame.FrameHeader.data_bits property.

property id¶: Convenience wrapper for the Frame.FrameHeader.id property.

property is_tbw¶: Convenience wrapper for the Frame.FrameHeader.is_tbw property.

property time¶: Convenience wrapper for the Frame.FramePayload.time property.

class lsl.reader.tbw.FrameHeader(frame_count=None, second_count=None, tbw_id=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.

property data_bits¶: 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.

property id¶: Function to parse the TBW ID field and return the stand number.

property is_tbw¶: 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.

class lsl.reader.tbw.FramePayload(timetag=None, 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.

property time¶: 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 as a lsl.reader.base.FrameTimestamp instance.

lsl.reader.tbw.get_data_bits(filehandle)¶: Find out the number of data bits used in the file be reading in the first frame.

lsl.reader.tbw.get_frames_per_obs(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.

lsl.reader.tbw.read_frame(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].

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

FramePayload - 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:

convert a frame in a file to a Frame object and
describe the format of the data in the file.

For reading in data, use the read_frame 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.Frame(header=None, payload=None, valid=True)¶

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

property channel_freqs¶: Convenience wrapper for the Frame.FrameHeader.channel_freqs property.

property is_tbf¶: Convenience wrapper for the Frame.FrameHeader.is_tbf property.

property time¶: Convenience wrapper for the Frame.FramePayload.time property.

class lsl.reader.tbf.FrameHeader(adp_id=None, frame_count=None, second_count=None, first_chan=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.

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

property is_tbf¶: Function to check if the data is really TBF. Returns True if the data is TBF, false otherwise.

class lsl.reader.tbf.FramePayload(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.

property time¶: 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 as a lsl.reader.base.FrameTimestamp instance.

lsl.reader.tbf.get_channel_count(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.get_first_channel(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.

lsl.reader.tbf.get_first_frame_count(filehandle)¶: Find and return the lowest frame count encountered in a TBF file.

lsl.reader.tbf.get_frames_per_obs(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.read_frame(filehandle, verbose=False)¶: Function to read in a single TBF frame (header+data) and store the contents as a Frame object.

Low-Level TBN – DP and ADP¶

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

FramePayload - 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:

convert a frame in a file to a Frame object and
describe the format of the data in the file.

For reading in data, use the read_frame 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:

get_sample_rate: read in the few frame of an open file handle and return the sampling rate of the data
get_frames_per_obs: read in the first several frames to see how many stands are found in the data.
..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.

Changed in version 0.5.0: Support for ECR 11 TBN header format change.

class lsl.reader.tbn.Frame(header=None, payload=None, valid=True)¶

Class that stores the information contained within a single TBN frame. It’s properties are FrameHeader and FramePayload 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.

property central_freq¶: Convenience wrapper for the Frame.FrameHeader.central_freq property.

property filter_code¶: Convenience wrapper for the Frame.FramePayload.filter_code property.

property gain¶: Convenience wrapper for the Frame.FrameHeader.gain property.

property id¶: Convenience wrapper for the Frame.FrameHeader.id property.

property is_tbn¶: Convenience wrapper for the Frame.FrameHeader.is_tbn property.

property sample_rate¶: Convenience wrapper for the Frame.FramePayload.sample_rate property.

property time¶: Convenience wrapper for the Frame.FramePayload.time property

class lsl.reader.tbn.FrameHeader(frame_count=None, tuning_word=None, tbn_id=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.

property central_freq¶: Convert the tuning word to a frequency in Hz.

property filter_code¶: Function to convert the sample rate in Hz to a filter code.

property id¶: Function to parse the TBN ID field and return a tuple of the stand number and polarization.

property is_tbn¶: 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.

class lsl.reader.tbn.FramePayload(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.

property time¶: 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 as a lsl.reader.base.FrameTimestamp instance.

lsl.reader.tbn.get_frames_per_obs(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.

lsl.reader.tbn.get_sample_rate(filehandle, nframe=None, filter_code=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.read_frame(filehandle, sample_rate=None, verbose=False)¶: Function to read in a single TBN frame (header+data) and store the contents as a Frame object.

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

FramePayload - 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:

convert a frame in a file to a Frame object and
describe the format of the data in the file.

For reading in data, use the read_frame 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.Frame(header=None, payload=None, valid=True)¶

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

property channel_freqs¶: Convenience wrapper for the Frame.FrameHeader.channel_freqs property.

property gain¶: Convenience wrapper for the Frame.FrameHeader.gain property.

property id¶: Convenience wrapper for the Frame.FramePayload.id property.

property integration_time¶: Convenience wrapper for the Frame.FramePayload.integration_time property.

property is_cor¶: Convenience wrapper for the Frame.FrameHeader.is_cor property.

property time¶: Convenience wrapper for the Frame.FramePayload.time property.

class lsl.reader.cor.FrameHeader(adp_id=None, frame_count=None, second_count=None, first_chan=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.

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

property is_cor¶: Function to check if the data is really COR. Returns True if the data is COR, false otherwise.

class lsl.reader.cor.FramePayload(timetag=None, navg=None, stand0=None, stand1=None, vis=None)¶

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

property id¶: Return a tuple of the two stands that contribute the this frame.

property integration_time¶: Return the integration time of the visibility in seconds.

property time¶: 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 as a lsl.reader.base.FrameTimestamp instance.

lsl.reader.cor.get_baseline_count(filehandle)¶: Find out the total number of baselines that are present by examining the first several COR records. Return the number of baselines found.

lsl.reader.cor.get_channel_count(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.get_frames_per_obs(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.read_frame(filehandle, verbose=False)¶: Function to read in a single COR frame (header+data) and store the contents as a Frame object.

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

FramePayload - 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:

convert a frame in a file to a Frame object and
describe the format of the data in the file.

For reading in data, use the read_frame 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:

get_beam_count: read in the first few frames of an open file handle and return how many beams are present in the file.
get_frames_per_obs: 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.Frame(header=None, payload=None, valid=True)¶

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

property central_freq¶: Convenience wrapper for the Frame.FramePayload.central_freq property.

property filter_code¶: Convenience wrapper for the Frame.FrameHeader.filter_code property.

property id¶: Convenience wrapper for the Frame.FrameHeader.id property.

property sample_rate¶: Convenience wrapper for the Frame.FrameHeader.sample_rate property.

property time¶: 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 as a lsl.reader.base.FrameTimestamp instance.

class lsl.reader.drx.FrameHeader(frame_count=None, drx_id=None, second_count=None, decimation=None, time_offset=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.

property filter_code¶: Function to convert the sample rate in Hz to a filter code.

property id¶: Parse the DRX ID into a tuple containing the beam (1 through 4), tunning (1 and 2), and polarization (0 and 1).

property sample_rate¶: Return the sample rate of the data in samples/second.

class lsl.reader.drx.FramePayload(timetag=None, tuning_word=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.

property central_freq¶: Function to set the central frequency of the DRX data in Hz.

lsl.reader.drx.get_beam_count(filehandle)¶: Find out how many beams are present by examining the first 32 DRX records. Return the number of beams found.

lsl.reader.drx.get_frames_per_obs(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.

lsl.reader.drx.get_sample_rate(filehandle, nframes=None, filter_code=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.read_frame(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.

Low-Level DR Spectrometer – DP and ADP¶

New in version 0.5.

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

Frame

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

FrameHeader - the spectrometer frame header object and

FramePayload - the spectral data object.

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

The functions defined in this module fall into two class:

convert a frame in a file to a Frame object and
describe the format of the data in the file.

For reading in data, use the read_frame function. It takes a python file- handle as an input and returns a fully-filled Frame object For describing the format of data in the file, three function are provided:

get_sample_rate - get the sample rate in the file

getFRAME_SIZE - get the total (header + data) frame size

get_ffts_per_integration - get the number of FFT windows per integration

get_transform_size - get the FFT length

get_integration_time - get the integration time

Note

This reader works with the most current version of the DR spectrometer data format as specified in the version 1.7. To read data created with previous versions of the DR spectrometer, use LSL version 0.5.2.

Changed in version 1.0.1: Added in new functions to help better describe the contents of a DR spectrometer file.

class lsl.reader.drspec.Frame(header=None, payload=None, valid=True)¶

Class that stores the information contained within a single DR spectrometer/ DRX frame. It’s properties are FrameHeader and FramePayloadLinear/FramePayloadStokes 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.

property central_freq¶: Convenience wrapper for the Frame.FramePayload.central_freq property.

property data_products¶: Convenience wrapper for the Frame.FrameHeder.data_products property.

property ffts_per_integration¶: Conveinence wrapper for the Frame.FrameHeader.ffts_per_integration property.

New in version 1.0.1.

property filter_code¶: Convenience wrapper for the Frame.FrameHeader.filter_code property.

property id¶: Convenience wrapper for the Frame.FrameHeader.id property.

property integration_time¶: Return the integration time for data in seconds.

New in version 1.0.1.

property is_linear¶: Convenience wrapper for the Frame.FrameHeder.is_linear property.

property is_stokes¶: Convenience wrapper for the Frame.FrameHeder.is_stokes property.

property sample_rate¶: Convenience wrapper for the Frame.FrameHeader.sample_rate property.

property time¶: 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 as a lsl.reader.base.FrameTimestamp instance.

property transform_size¶: Find out what the transform size is.

New in version 1.0.1.

class lsl.reader.drspec.FrameHeader(beam=0, format=0, decimation=None, time_offset=None, nints=None)¶

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

property data_products¶: Return a list of data products contained in the file.

New in version 0.6.0.

property ffts_per_integration¶: Return the number of FFT windows per integration.

New in version 1.0.1.

property filter_code¶: Function to convert the sample rate in Hz to a filter code.

property id¶: Return the beam the frame corresponds to.

property is_linear¶: Return whether or not the frame contains linear polarization products or not.

New in version 0.6.0.

property is_stokes¶: Return whether or not the frame contains Stokes polarization parameters or not.

New in version 0.6.0.

property sample_rate¶: Return the sample rate of the data in samples/second.

class lsl.reader.drspec.FramePayload(timetag=None, tuning_words=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.

property central_freq¶: Function to set the central frequency of the DRX data in Hz.

lsl.reader.drspec.get_data_products(filehandle)¶: Find out the data products contained in the file by looking at a frame.

lsl.reader.drspec.get_ffts_per_integration(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.get_frame_size(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.get_integration_time(filehandle)¶: Find out what the integration time is at the current file location.

lsl.reader.drspec.get_sample_rate(filehandle, nframes=None, filter_code=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.get_transform_size(filehandle)¶: Find out what the transform size in a file is at the current file location.

lsl.reader.drspec.is_linear(filehandle)¶: Find out if the file contains linear polarization products or not.

lsl.reader.drspec.is_stokes(filehandle)¶: Find out if the file contains Stokes parameters or not.

lsl.reader.drspec.read_frame(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.

Low-Level VIDF¶

Python module to read in VDIF data. This module defines the following classes for storing the VIDF 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 VDIF frame header object and

FramePayload - the VDIF frame data object.

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

The functions defined in this module fall into two class:

convert a frame in a file to a Frame object and
describe the format of the data in the file.

For reading in data, use the read_frame 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 VDIF frames and returns a ObservingBlock object.

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

get_thread_count: read in the first few frames of an open file handle and return how many threads are present in the file.

class lsl.reader.vdif.Frame(header=None, payload=None, valid=True)¶

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

property central_freq¶: Convenience wrapper for the Frame.FrameHeader.central_freq property.

property extended_user_data¶: Convenience wrapper for the Frame.FrameHeader.extended_user_data property.

property id¶: Convenience wrapper for the Frame.FrameHeader.id property.

property sample_rate¶: Convenience wrapper for the Frame.FrameHeader.sample_rate property.

property time¶: Convenience wrapper for the Frame.FrameHeader.time property.

class lsl.reader.vdif.FrameHeader(is_invalid=0, is_legacy=0, seconds_from_epoch=0, ref_epoch=0, frame_in_second=0, version=1, nchan=0, frame_length=0, is_complex='C', bits_per_sample=0, thread_id=0, station_id=0, extended_data_1=None, extended_data_2=None, extended_data_3=None, extended_data_4=None, sample_rate=0.0, central_freq=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.

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

property id¶: Return a two-element tuple of the station ID and thread ID.

Note

The station ID is always returned as numeric.

property time¶: Function to convert the time tag to seconds since the UNIX epoch as a lsl.reader.base.FrameTimestamp instance.

class lsl.reader.vdif.FramePayload(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.

lsl.reader.vdif.get_frame_size(filehandle, nframes=None)¶: Find out what the frame size is in bytes from a single observation.

lsl.reader.vdif.get_frames_per_second(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.get_sample_rate(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.

lsl.reader.vdif.get_thread_count(filehandle)¶: Find out how many thrads are present by examining the first 1024 records. Return the number of threads found.

lsl.reader.vdif.has_guppi_header(filehandle)¶: Determine if a VDIF file has a GUPPI header or not.

New in version 2.0.0.

lsl.reader.vdif.read_frame(filehandle, sample_rate=0.0, central_freq=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.read_guppi_header(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.

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.SyncError(type='Mark5C', 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 2.

lsl.reader.errors.list_error_codes(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.

Changed in version 0.5: Removed support for DRX FrameBuffers since they shouldn’t be needed.

Changed in version 0.6: Removed support for TBW FrameBuffers since they didn’t really work.

Changed in version 1.0.0: Added back in the DRX FrameBuffers since they might be useful. Dropped TBW support from within the FrameBufferBase class.

Changed in version 1.0.2: Added support for the LWA-SV ADP DRX8 mode

Changed in version 1.1.4: Dropped support for the LWA-SV ADP DRX8 mode

Changed in version 1.2.1: Added support for the LWA-SV TBF and COR modes

class lsl.reader.buffer.CORFrameBuffer(chans, nsegments=5, reorder=False)¶

Bases: lsl.reader.buffer.FrameBufferBase

A sub-type of FrameBufferBase specifically for dealing with COR frames. See lsl.reader.buffer.FrameBufferBase 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 5)
reorder: 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
1	10
2	20
5	50

create_fill(key, frameParameters)¶: Create a ‘fill’ frame of zeros using an existing good packet as a template.

get_figure_of_merit(frame)¶: Figure of merit for sorting frames. For TBF this is: frame.payload.timetag

get_max_frames()¶: 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.

class lsl.reader.buffer.DRXFrameBuffer(beams=[], tunes=[1, 2], pols=[0, 1], nsegments=20, reorder=False)¶

Bases: lsl.reader.buffer.FrameBufferBase

A sub-type of FrameBufferBase specifically for dealing with DRX frames. See lsl.reader.buffer.FrameBufferBase 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)
reorder: 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
Segments	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

create_fill(key, frameParameters)¶: Create a ‘fill’ frame of zeros using an existing good packet as a template.

get_figure_of_merit(frame)¶

Figure of merit for sorting frames. For DRX it is:: <frame timetag in ticks>

get_max_frames()¶: 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.

class lsl.reader.buffer.FrameBufferBase(mode='TBN', stands=[], beams=[], tunes=[], pols=[], chans=[], threads=[], nsegments=6, reorder=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.

create_fill(key, frameParameters)¶

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

This will be overridden by sub-classes of FrameBufferBase.

property 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(key_to_return=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.

get_figure_of_merit(frame)¶

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

This will be overridden by sub-classes of FrameBufferBase.

get_max_frames()¶

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 FrameBufferBase.

is_empty()¶: Determine if there is anything in the buffer or not. Returns False if there is, True if there is not.

property 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

require_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:

The current buffer fill level
The numer of full and partial buffer dumps preformed
The number of missing frames that fill packets needed to be created for
The number of frames that arrived too late to be incorporated into one of the ring buffers

class lsl.reader.buffer.TBFFrameBuffer(chans, nsegments=25, reorder=False)¶

Bases: lsl.reader.buffer.FrameBufferBase

A sub-type of FrameBufferBase specifically for dealing with TBF frames. See lsl.reader.buffer.FrameBufferBase 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)
reorder: 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

create_fill(key, frameParameters)¶: Create a ‘fill’ frame of zeros using an existing good packet as a template.

get_figure_of_merit(frame)¶: Figure of merit for sorting frames. For TBF this is: frame.payload.timetag

get_max_frames()¶: 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.

class lsl.reader.buffer.TBNFrameBuffer(stands=[], pols=[0, 1], nsegments=20, reorder=False)¶

Bases: lsl.reader.buffer.FrameBufferBase

A sub-type of FrameBufferBase specifically for dealing with TBN frames. See lsl.reader.buffer.FrameBufferBase 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)
reorder: 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
Segments	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

create_fill(key, frameParameters)¶: Create a ‘fill’ frame of zeros using an existing good packet as a template.

get_figure_of_merit(frame)¶

Figure of merit for sorting frames. For TBN it is:: <frame timetag in ticks>

get_max_frames()¶: 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.

class lsl.reader.buffer.VDIFFrameBuffer(threads=[0, 1], nsegments=10, reorder=False)¶

Bases: lsl.reader.buffer.FrameBufferBase

A sub-type of FrameBufferBase specifically for dealing with VDIF frames. See lsl.reader.buffer.FrameBufferBase 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)
reorder: whether or not to reorder frames returned by get() or flush() by stand/polarization (default is False)

create_fill(key, frameParameters)¶: Create a ‘fill’ frame of zeros using an existing good packet as a template.

get_figure_of_merit(frame)¶: Figure of merit for sorting frames. For VIDF this is: seconds_from_epoch * 1000000 + frame_in_second

get_max_frames()¶: 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.

Data Writers¶

Single-Dish FITS¶

SDFITS Standard

Module for writing spectrometer output to a SDFITS file. The SDFITS created by this modulefiles closely follow the Parkes variant of the SDFITS convention (see [http://fits.gsfc.nasa.gov/registry/sdfits.html]). The main differences between the two is that the LWA SDFITS do not contain calbration or weather information. This, however, should not stop the files from being loaded into CASA with the ATNF Spectral Analysis Package (ASAP).

Changed in version 0.5.0: The classes and functions defined in this module are based heavily off the lsl.writer.fitsidi writer.

class lsl.writer.sdfits.Sd(filename, ref_time=0.0, verbose=False, memmap=None, overwrite=False)¶

Class for storing spectrometer data and writing the data, along with array frequency setup, etc., to a SDFITS file that can be read into CASA via the sd.scantable() function.

add_comment(comment)¶: Add a comment to data.

New in version 1.2.4.

add_data_set(obsTime, intTime, beam, data, pol='XX')¶: Create a SpectrometerData object to store a collection of spectra.

add_header_keyword(name, value, comment=None)¶: Add an additional entry to the header of the primary HDU.

New in version 2.0.0.

add_history(history)¶: Add a history entry to the data.

New in version 1.2.4.

property astro_ref_time¶: Convert a reference time string to an lsl.astro.date object.

close()¶: Close out the file.

parse_time(ref_time)¶: Given a time as either a integer, float, string, or datetime object, convert it to a string in the formation ‘YYYY-MM-DDTHH:MM:SS’.

set_frequency(freq)¶: Given a numpy array of frequencies, set the relevant common observation parameters and add an entry to the self.freq list.

set_geometry(*args, **kwds)¶: Given a station and an array of stands, set the relevant common observation parameters and add entries to the self.array list.

set_observer(observer, project='UNKNOWN', mode='ZA')¶: Set the observer name, project, and observation mode (if given) to the self.observer, self.project, and self.mode attributes, respectively.

New in version 2.0.0.

set_site(site)¶: Set the TELESCOP keyword in the primary HDU using an lsl.common.stations.LWAStation object.

set_stokes(polList)¶: Given a list of Stokes parameters, update the object’s parameters.

write()¶: Fill in the SDFITS file will all of the tables in the correct order.

FITS IDI¶

FITS IDI Standard

Module for writing correlator output to a FITS IDI file. The classes and functions defined in this module are based heavily off the lwda_fits library.

Note

Some software that deal with FITS IDI files, e.g. AIPS, does not support FITS IDI files with more than 99 antennas. See the lsl.writer.fitsidi.aips class for a FITS IDI writer that respects this limit.

Changed in version 1.1.4: Fixed a conjugation problem in the visibilities saved to a FITS-IDI file Added support for writing user-specified weights to a FITS-IDI file

Changed in version 1.2.2: Added support for writing multiple IFs to the same FITS-IDI file

class lsl.writer.fitsidi.Aips(filename, ref_time=0.0, verbose=False, memmap=None, overwrite=False)¶: Sub-class of the FITS IDI writer for making files that should work with AIPS nicely. AIPS imposes a limit on antenna number of two digits (1-99). This sub-class overwrite the set_geometry() function with one that enforces the two digit limit and maps accordingly. It also sets the FITS LWATYPE keyword in the primary HDU to a value of IDI-AIPS-ZA to distinguish files written by this writer from the standard IDI writer.

class lsl.writer.fitsidi.ExtendedIdi(filename, ref_time=0.0, verbose=False, memmap=None, overwrite=False)¶: Sub-class of the FITS IDI writer for making files that support up to 65,535 antennas. This is done by changing the packing of baselines stored in the UVDATA table. The new packing for baseline (i,j) is: (i << 16) & (j) It also sets the FITS LWATYPE keyword in the primary HDU to a value of IDI-EXTENDED-ZA to distinguish files written by this writer from the standard IDI writer.

class lsl.writer.fitsidi.Idi(filename, ref_time=0.0, verbose=False, memmap=None, overwrite=False)¶

Class for storing visibility data and writing the data, along with array geometry, frequency setup, etc., to a FITS IDI file that can be read into AIPS via the FITLD task.

add_comment(comment)¶: Add a comment to data.

New in version 1.2.4.

add_history(history)¶: Add a history entry to the data.

New in version 1.2.4.

close()¶: Close out the file.

read_array_geometry()¶: Return a tuple with the array geodetic position and the local positions for all antennas defined in the ARRAY_GEOMETRY table.

read_array_mapper()¶: Return a tuple with the array NOSTA mapper and inverse mapper (both dictionaries. If the stand IDs have not been mapped, return None for both.

set_geometry(site, antennas, bits=8)¶: Given a station and an array of stands, set the relevant common observation parameters and add entries to the self.array list.

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.

write()¶: Fill in the FITS-IDI file will all of the tables in the correct order.

UVFITS¶

Module for writing correlator output to a UVFITS file. The classes and functions defined in this module are based heavily off the lwda_fits library.

Note

For arrays with between 256 and 2048 antennas, the baseline packing follows the MIRIAD convention.

class lsl.writer.uvfits.Uv(filename, ref_time=0.0, verbose=False, memmap=None, overwrite=False)¶

Class for storing visibility data and writing the data, along with array geometry, frequency setup, etc., to a UVFITS file that can be read into AIPS via the UVLOD task.

add_comment(comment)¶: Add a comment to data.

New in version 1.2.4.

add_history(history)¶: Add a history entry to the data.

New in version 1.2.4.

close()¶: Close out the file.

read_array_geometry(dummy=False)¶: Return a tuple with the array geodetic position and the local positions for all antennas defined in the AIPS AN table.

read_array_mapper(dummy=False)¶: Return a tuple with the array NOSTA mapper and inverse mapper (both dictionaries. If the stand IDs have not been mapped, return None for both.

set_geometry(site, antennas, bits=8)¶: Given a station and an array of stands, set the relevant common observation parameters and add entries to the self.array list.

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.

write()¶: Fill in the FITS-IDI file will all of the tables in the correct order.

Measurement Set¶

Module for writing correlator output to a CASA measurement set.

New in version 1.2.1.

class lsl.writer.measurementset.Ms(filename, ref_time=0.0, verbose=False, memmap=None, overwrite=False)¶

Class for storing visibility data and writing the data, along with array geometry, frequency setup, etc., to a CASA measurement set.

add_data_set(obsTime, intTime, baselines, visibilities, pol='XX', source='z')¶: Create a UVData object to store a collection of visibilities for the specified TAI MJD time.

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 as part of the baselines.

Changed in version 1.1.0: Added a new ‘source’ keyword to set the phase center for the data. This can either by ‘z’ for zenith or a ephem.Body instances for a point on the sky.

add_header_keyword(name, value, comment=None)¶: Add an additional entry to the header of the primary HDU.

New in version 2.0.0.

close()¶: Close out the file.

set_geometry(site, antennas, bits=8)¶: Given a station and an array of stands, set the relevant common observation parameters and add entries to the self.array list.

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.

write()¶: Fill in the FITS-IDI file will all of the tables in the correct order.

VDIF¶

VDIF Standard (PDF)

Module to write VDIF frames. The implementation of this module is similar to that of lsl.sim.tbw in that the primary element defined in this module is a Frame object which as attribute functions that can create a numpy representation of the raw frame and write that raw frame to an open file- handle.

Computing Spectra¶

lsl.correlator.fx.SpecMaster(signals, LFFT=64, window=<function null_window>, pfb=False, verbose=False, sample_rate=None, central_freq=0.0, clip_level=0)¶: A more advanced version of calcSpectra that uses the _spec C extension to handle all of the P.S.D. calculations in parallel. Returns a two- element tuple of the frequencies (in Hz) and PSDs in linear power/RBW.

Note

SpecMaster currently average all data given and does not support the SampleAverage keyword that calcSpectra does.

Changed in version 1.2.5: Added the ‘pfb’ keyword.

lsl.correlator.fx.StokesMaster(signals, antennas, LFFT=64, window=<function null_window>, pfb=False, verbose=False, sample_rate=None, central_freq=0.0, clip_level=0)¶: Similar to SpecMaster, but accepts an array of signals and a list of antennas in order to compute the PSDs for the four Stokes parameters: I, Q, U, and V. Returns a two-element tuple of the frequencies (in Hz) and PSDs in linear power/RBW. The PSD are three dimensional with dimensions Stokes parameter (0=I, 1=Q, 2=U, 3=V) by stand by channel).

Changed in version 1.2.5: Added the ‘pfb’ keyword.

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

FXStokes - calculate Stokes 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
StokesMaster - similar to SpecMaster but computes all four Stokes parameters
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.

Changed in version 1.0.1: Removed SpecMasterP.

Changed in version 1.0.0: All of the functions here now return all ‘LFFT’ channels.

Baseline Utilities¶

lsl.correlator.uvutils.get_baselines(antennas, antennas2=None, include_auto=False, indicies=False)¶: Generate a list of two-element tuples that describe which antennae compose each of the output uvw triplets from compute_uvw/compute_uv_track. 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.baseline_to_antennas(baseline, antennas, antennas2=None, baseline_list=None, include_auto=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.antennas_to_baseline(ant1, ant2, antennas, antennas2=None, baseline_list=None, include_auto=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.compute_uvw(antennas, HA=0.0, dec=34.07, freq=49000000.0, site=<LWAStation id='VL', name='LWA1', lat=34:04:08.0, long=-107:37:42.1, elev=2133.6, pressure=0.0, horizon=0:00:00.0, antennas=[...], interface=<LSLInterface backend='lsl.common.dp', mcs='lsl.common.mcs', sdf='lsl.common.sdf', metabundle='lsl.common.metabundle', sdm='lsl.common.sdm'>>, include_auto=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 a given site. 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.

Changed in version 1.0.0: Added a keyword (site) to specify the station used for the observation.

Changed in version 1.1.2: Updated to work with lists in a transparent manner.

Changed in version 2.0.1: Added support for ephem.Angle and astropy.coordinates.Angle instances for HA and dec. Added support for astropy.coordinates.EarthLocation instances for site.

lsl.correlator.uvutils.compute_uv_track(antennas, dec=34.07, freq=49000000.0, site=<LWAStation id='VL', name='LWA1', lat=34:04:08.0, long=-107:37:42.1, elev=2133.6, pressure=0.0, horizon=0:00:00.0, antennas=[...], interface=<LSLInterface backend='lsl.common.dp', mcs='lsl.common.mcs', sdf='lsl.common.sdf', metabundle='lsl.common.metabundle', sdm='lsl.common.sdm'>>)¶: Whereas compute_uvw provides the uvw coverage at a particular time, compute_uv_track 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 compute_uvw, 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.

Changed in version 1.0.0: Added a keyword (site) to specify the station used for the observation.

Changed in version 2.0.1: Added support for ephem.Angle and astropy.coordinates.Angle instances for dec. Added support for astropy.coordinates.EarthLocation instances for site.

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 null_window>)¶: 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.fft16(signal, N, window=<function null_window>)¶: Sub-type of lsl.correlator.filterbank.fft that uses 16 taps.

lsl.correlator.filterbank.fft2(signal, N, window=<function null_window>)¶: Sub-type of lsl.correlator.filterbank.fft that uses two taps.

lsl.correlator.filterbank.fft32(signal, N, window=<function null_window>)¶: Sub-type of lsl.correlator.filterbank.fft that uses 32 taps.

lsl.correlator.filterbank.fft4(signal, N, window=<function null_window>)¶: Sub-type of lsl.correlator.filterbank.fft that uses four taps.

lsl.correlator.filterbank.fft8(signal, N, window=<function null_window>)¶: Sub-type of lsl.correlator.filterbank.fft that uses eight taps.

FX Correlator¶

lsl.correlator.fx.null_window(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, include_auto=False, verbose=False, window=<function null_window>, pfb=False, sample_rate=None, central_freq=0.0, Pol='XX', gain_correct=False, return_baselines=False, clip_level=0, phase_center='z')¶: 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.

Changed in version 1.0.0: Added a phase-center keyword that accept a two-element tuple of azimuth and elelvation (in degrees) to change where the correlations are phased to

Changed in version 1.1.0: Made the ‘phase_center’ keyword more flexible. It can now be either: * ‘z’ to denote the zenith, * a ephem.Body instances which has been computed for the observer, or * a two-element tuple of azimuth, elevation in degrees.

Changed in version 1.2.5: Added the ‘pfb’ keyword.

Changed in version 2.0.1: Added support for phase_center to be an astropy.coordinates.AltAz instance

lsl.correlator.fx.FXStokes(signals, antennas, LFFT=64, overlap=1, include_auto=False, verbose=False, window=<function null_window>, pfb=False, sample_rate=None, central_freq=0.0, gain_correct=False, return_baselines=False, clip_level=0, phase_center='z')¶: 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 2.0.1: Added support for phase_center to be an astropy.coordinates.AltAz instance

Changed in version 1.0.0: Added a phase_center keyword that accept a two-element tuple of azimuth and elelvation (in degrees) to change where the correlations are phased to

Changed in version 1.1.0: Made the ‘phase_center’ keyword more flexible. It can now be either: * ‘z’ to denote the zenith, * a ephem.Body instances which has been computed for the observer, or * a two-element tuple of azimuth, elevation in degrees.

Changed in version 1.2.5: Added the ‘pfb’ keyword.

Imaging¶

Data Representation¶

Classes to hold visibility data that are used internally with LSL.

class lsl.imaging.data.PolarizationDataSet(polarization, data=None, weight=None, mask=None)¶

Class to hold the visibility data/weight/mask for a single polarization.

append(data, weight=None, mask=None)¶: Append a new visibility to the object.

copy()¶: Return a copy of the object.

extend(data, weight=None, mask=None)¶: Extend the object with a collection of visibilites.

property nbaseline¶: The number of baselines contained in the data.

sort(order)¶: Apply the specified ordering on the object.

subset(selection)¶: Return a subset of the data.

class lsl.imaging.data.VisibilityData(data=None)¶

Class to hold multiple integrations of visibility data.

append(value)¶: Append a new integration stored as a VisibilityDataSet to the object.

property baselines¶: Return a list baselines contained in the first VisbilityDataSet object.

copy(include_pols=True)¶: Return a copy of the object. Be default this includes copies of all of the associated PolarizationDataSet objects stored in the individual VisibilityDataSet sets. Setting ‘include_pols’ to False will not copy these objects.

extend(values)¶: Append a collection of new integration stored as VisibilityDataSet to the objects.

property freq¶: Return a list polarizations contained in the first VisbilityDataSet object.

get_antenna_subset(include=None, exclude=None, indicies=True)¶: Return a copy of the data containing baselines that meet the specified antenna selection criteria. The selection is governed by the ‘include’, ‘exclude’, and ‘indicies’ keywords. If ‘include’ is not None, only baselines containing antennas in the list are selected. If ‘exclude’ is not None, only baselines not containing antennas in the list are selected. If both ‘include’ and ‘exclude’ are provided, the ‘include’ list has priority. ‘indicies’ sets whether or not the selection criteria are provided as indicies of the antennas stored in the antennaarray attribute or are stand numbers.

get_uv_range(min_uv=0.0, max_uv=inf)¶: Return a copy of the data containing only baselines with the (u,v) distances allowed by the ‘min_uv’ and ‘max_uv’ cuts.

property jds¶: Return a list of JDs for all VisibilityDataSets contained.

property mjds¶: Return a list of MJDs for all VisibilityDataSets contained.

property nbaseline¶: The number of baselines contained in the first VisbilityDataSet object.

property nchan¶: The number of frequency channels contained in the first VisbilityDataSet object.

property npol¶: The number of polarizations contained in the first VisbilityDataSet object.

property pols¶: Return a list polarizations contained in the first VisbilityDataSet object.

pop(index=- 1)¶: Pop and return the VisibilityDataSet specified by the provided index.

rephase(new_phase_center, ignore_errors=False)¶: Shift the phase center for all of the integrations stored.

sort()¶: Sort the VisibilityDataSet objects contained by the JD of the integrations.

class lsl.imaging.data.VisibilityDataSet(jd, freq, baselines, uvw, antennaarray=None, phase_center=None, **kwds)¶

Class to wrap a single integration of visibility data.

append(value)¶: Append a new PolarizationDataSet object. If the polarization already exists it is replaced.

copy(include_pols=True)¶: Return a copy of the object. Be default this includes copies of all of the associated PolarizationDataSet objects. Setting ‘include_pols’ to False will not copy these objects.

get_antenna_subset(include=None, exclude=None, indicies=True)¶: Return a copy of the data containing baselines that meet the specified antenna selection criteria. The selection is governed by the ‘include’, ‘exclude’, and ‘indicies’ keywords. If ‘include’ is not None, only baselines containing antennas in the list are selected. If ‘exclude’ is not None, only baselines not containing antennas in the list are selected. If both ‘include’ and ‘exclude’ are provided, the ‘include’ list has priority. ‘indicies’ sets whether or not the selection criteria are provided as indicies of the antennas stored in the antennaarray attribute or are stand numbers.

get_uv_range(min_uv=0.0, max_uv=inf)¶: Return a copy of the data containing only baselines with the (u,v) distances allowed by the ‘min_uv’ and ‘max_uv’ cuts.

property mjd¶: The MJD that the data correspond to.

property nbaseline¶: The number of baselines in the data.

property nchan¶: The number of frequency channels in the data.

property npol¶: The number of polarizations stored.

rephase(new_phase_center)¶: Shift the phase center of the data to a new phase center.

sort(order=None)¶: Sort the stored data using the order provided in the ‘order’ keyword. If not ordering is provided, the data are sorted by baseline pair.

Imaging¶

Module to support imaging correlated data. This module provides utilities to read FITS IDI files into lsl.imaging.data.VisibilityDataSet or lsl.imaging.data.VisibilityData object (as described in lsl.imaging.data) and build AIPY ImgW instances from the data.

New in version 0.5.0.

Changed in version 1.0.0: Added support for UVFITS files and CASA measurement sets

Changed in version 1.0.1: Added the plot_gridded_image() function

Changed in version 1.1.0: Added the get_image_radec() and get_image_azalt() functions to complement plot_gridded_image() and make it easier to work with phase centers that are not at zenith. Added in the ImgWPlus class to add support for imaging weighting and tapering.

Changed in version 1.1.2: Added support for CASA MeasurementSets that are stored as a tarball

Changed in version 1.1.4: Fixed a conjugation problem in the visibilities read from a FITS-IDI file

lsl.imaging.utils.CorrelatedData(filename, verbose=False)¶: Read in and work with FITS IDI and UVFITS files. Returns either a CorrelateDataIDI or CorrelatedDataUV instance.

class lsl.imaging.utils.CorrelatedDataIDI(filename)¶

Class to make accessing information about a FITS IDI easy. This wraps all of the “messy” machinery needed to extract both the metadata and data from the file and return them as common LSL objects.

This class has three main attributes to interact with:

get_antennaarray - Return a lsl.sim.vim.AntennaArray instance
that represents the array where the data was obtained. This is useful for simulation proposes and computing source positions.
get_observer - Return a ephem.Observer instance representing the array
get_data_set - Return a lsl.imaging.data.VisibilityDataSet or
lsl.imaging.data.VisibilityData object for all baselines for a given set of observations

The class also includes a variety of useful metadata attributes:

pols - Numpy array of polarization product codes
freq - Numpy array of frequency channels in Hz
station - LSL lsl.common.stations.LWAStation instance for the
array
date_obs - Datetime object for the reference date of the FIT IDI file
antennas - List of lsl.common.stations.Antenna instances

Note

The CorrelatedData.antennas attribute should be used over CorrelatedData.station.antennas since the mapping in the FITS IDI file may not be the same as the digitizer order.

get_data_set(sets, include_auto=False, sort=True, min_uv=0, max_uv=inf)¶: Return a lsl.imaging.data.VisibilityDataSet or lsl.imaging.data.VisibilityData object for all baselines for a given set of observations for the specified data set. By default this excludes the autocorrelations. To include autocorrelations set the value of ‘include_auto’ to True. Setting the ‘sort’ keyword to False will disable the baseline sorting. Optionally, baselines with lengths between min_uv and max_uv can only be returned.

Note

min_uv and max_uv should be specified in lambda

Changed in version 1.1.0: ‘set’ can now be either an integer or a list to pull back multiple integrations.

class lsl.imaging.utils.CorrelatedDataMS(filename)¶

Class to make accessing information about a MS easy. This wraps all of the “messy” machinery needed to extract both the metadata and data from the file and return them as common LSL objects.

This class has three main attributes to interact with:

get_antennaarray - Return a lsl.sim.vim.AntennaArray instance
that represents the array where the data was obtained. This is useful for simulation proposes and computing source positions.
get_observer - Return a ephem.Observer instance representing the array
get_data_set - Return a lsl.imaging.data.VisibilityDataSet or
lsl.imaging.data.VisibilityData object of all baselines for a given set of observations

The class also includes a variety of useful metadata attributes:

pols - Numpy array of polarization product codes
freq - Numpy array of frequency channels in Hz
station - LSL lsl.common.stations.LWAStation instance for the
array
date_obs - Datetime object for the reference date of the FIT IDI file
antennas - List of lsl.common.stations.Antenna instances

Note

The CorrelatedDataMS.antennas attribute should be used over CorrelatedDataMS.station.antennas since the mapping in the MS may not be the same as the digitizer order.

get_data_set(sets, include_auto=False, sort=True, min_uv=0, max_uv=inf)¶: Return a lsl.imaging.data.VisibilityDataSet or lsl.imaging.data.VisibilityData object for the specified data set. By default this excludes the autocorrelations. To include autocorrelations set the value of ‘include_auto’ to True. Setting the ‘sort’ keyword to False will disable the baseline sorting. Optionally, baselines with lengths between min_uv and max_uv can only be returned.

Note

min_uv and max_uv should be specified in lambda

class lsl.imaging.utils.CorrelatedDataUV(filename)¶

Class to make accessing information about a UVFITS file easy. This wraps all of the “messy” machinery needed to extract both the metadata and data from the file and return them as common LSL objects.

This class has three main attributes to interact with:

get_antennaarray - Return a lsl.sim.vim.AntennaArray instance
that represents the array where the data was obtained. This is useful for simulation proposes and computing source positions.
get_observer - Return a ephem.Observer instance representing the array
get_data_set - Return a lsl.imaging.data.VisibilityDataSet or
lsl.imaging.data.VisibilityData object of all baselines for a given set of observations

The class also includes a variety of useful metadata attributes:

pols - Numpy array of polarization product codes
freq - Numpy array of frequency channels in Hz
station - LSL lsl.common.stations.LWAStation instance for the
array
date_obs - Datetime object for the reference date of the FIT IDI file
antennas - List of lsl.common.stations.Antenna instances

Note

The CorrelatedDataUV.antennas attribute should be used over CorrelatedDataUV.station.antennas since the mapping in the UVFITS file may not be the same as the digitizer order.

get_data_set(sets, include_auto=False, sort=True, min_uv=0, max_uv=inf)¶: Return a lsl.imaging.data.VisibilityDataSet or lsl.imaging.data.VisibilityData object for the specified data set. By default this excludes the autocorrelations. To include autocorrelations set the value of ‘include_auto’ to True. Setting the ‘sort’ keyword to False will disable the baseline sorting. Optionally, baselines with lengths between min_uv and max_uv can only be returned.

Note

min_uv and max_uv should be specified in lambda

Changed in version 1.1.0: ‘set’ can now be either an integer or a list to pull back multiple integrations.

class lsl.imaging.utils.ImgWPlus(size=100, res=1, wres=0.5, mf_order=0)¶

Sub-class of the aipy.img.ImgW class that adds support for different visibility weighting scheme and uv plane tapering. This class also adds in a couple of additional methods that help determine the size of the field of view and the pixels near the phase center.

bm_image(center=0, 0, term=None, weighting='natural', local_fraction=0.5, robust=0.0, taper=0.0, 0.0)¶

Return the inverse FFT of the sample weightings (for all mf_order terms, or the specified term if supplied), with the 0,0 point moved to ‘center’. In the images return north is up and east is to the left.

There are a few keywords that control how the image is formed. There are:

weighting - The weighting scheme (‘natural’, ‘uniform’, or
‘briggs’) used on the data;

local_fraction - The fraction of the uv grid that is consider
“local” for the ‘uniform’ and ‘briggs’ methods;

robust - The value for the weighting robustness under the
‘briggs’ method; and

taper - The size of u and v Gaussian tapers at the 30% level.

property field_of_view¶: Return the approximate size of the field of view in radians. The field of view calculate is based off the maximum and minimum values of L found for the inverted uv matrix.

image(center=0, 0, weighting='natural', local_fraction=0.5, robust=0.0, taper=0.0, 0.0)¶

Return the inverse FFT of the UV matrix, with the 0,0 point moved to ‘center’. In the images return north is up and east is to the left.

There are a few keywords that control how the image is formed. There are:

weighting - The weighting scheme (‘natural’, ‘uniform’, or
‘briggs’) used on the data;

local_fraction - The fraction of the uv grid that is consider
“local” for the ‘uniform’ and ‘briggs’ methods;

robust - The value for the weighting robustness under the
‘briggs’ method; and

taper - The size of u and v Gaussian tapers at the 30% level.

property pixel_size¶: Return the approximate size of pixels at the phase center in radians. The pixel size is averaged over the four pixels that neighboor the phase center.

put(uvw, data, wgts=None, invker2=None, verbose=True)¶: Same as Img.put, only now the w component is projected to the w=0 plane before applying the data to the UV matrix.

lsl.imaging.utils.build_gridded_image(data_set, size=80, res=0.5, wres=0.1, pol='XX', chan=None, im=None, verbose=True)¶: Given a lsl.imaging.data.VisibilityDataSet object, build an aipy.img.ImgW object of gridded uv data which can be used for imaging. The ImgW object itself is returned by this function to make it more versatile.

lsl.imaging.utils.get_image_azalt(gimg, aa, phase_center='z', shifted=True)¶

Given a gridded image generated by the build_gridded_image() function and an AntennaArray instance, return a two-element tuple containing the azimuth and elevation (altitude), both in radians, for each pixel in the image.

The ‘phase_center’ keyword controls what the phase center of the image is and defaults to zenith.

lsl.imaging.utils.get_image_radec(gimg, aa, phase_center='z', shifted=True)¶

Given a gridded image generated by the build_gridded_image() function and an AntennaArray instance, return a two-element tuple containing the RA and dec. values (in radians) for each pixel in the image.

The ‘phase_center’ keyword controls what the phase center of the image is and defaults to zenith.

lsl.imaging.utils.plot_gridded_image(ax, gimg, shifted=True, origin='lower', interpolation='nearest', **kwargs)¶: Given a blank matplotlib axes instance and a gridded image generated by the build_gridded_image() function, plot the image on the axes and setup the basic coordinate system. This function returns the matplotlib object added to the plot

Changed in version 1.2.1: Changed the function to return the matplotlib object plotted so that colorbars can be added

Changed in version 1.1.0: Added a ‘shifted’ keyword to control whether or not the image is centered or not.

New in version 1.0.1.

Plot Overlays¶

Module that provides a variety of overlays for all-sky images. These overlays include:

the locations and names of sources,

the horizon,

a graticle showing lines of constant RA and dec., and

a graticle showing lines of constant azimuth and elevation.

All of the functions in this module accept a matplotlib axes instances that is used for plotting.

New in version 1.0.1.

Changed in version 1.1.0: Added support for overlaying on images with non-zenith phase centers

lsl.imaging.overlay.graticule_azalt(ax, antennaarray, phase_center='z', label=True, color='white')¶: For a matplotlib axis instance showing an image of the sky, plot lines of constant azimuth and elevation. Elevations are spaced at 20 degree intervals and azimuths are spaced at 45 degree intervals

lsl.imaging.overlay.graticule_radec(ax, antennaarray, phase_center='z', label=True, color='white')¶: For a matplotlib axis instance showing an image of the sky, plot lines of constant declinate and RA. Declinations are spaced at 20 degree intervals and RAs are spaced at 2 hour intervals.

lsl.imaging.overlay.horizon(ax, antennaarray, phase_center='z', color='white')¶: For a matplotlib axis instance showing an image of the sky, plot the horizon.

Changed in version 1.1.0: Added a new argument for the AntennaArray instance to provide a uniform default call for all functions.

lsl.imaging.overlay.sources(ax, antennaarray, srcs, phase_center='z', label=True, marker='x', color='white')¶: For a matplotlib axis instance showing an image of the sky, plot the locations of the srcs given in the ‘srcs’ dictionary.

Basic Image Analysis¶

Module for analyzing images. Currently, this module supports:

estimating the position-dependent background level in the image
finding point sources

New in version 1.1.0.

lsl.imaging.analysis.estimate_background(image, window=32)¶

Given a 2-D image, estimate and return the background a la SExtractor.

This works by:

Dividing the image into a number of half-overlapped tiles that are ‘window’ by ‘window’ pixels in size.
Computing the mean and standard deviation within the tile both with and without 3*sigma clipping applied.
Using the tile statistics, determine if the tile is empty, i.e., the standard deviation has changed by less than 20%, or full.
1. If the tile is empty, use the clipped mean for the background.
2. Otherwise, use 2.5*median - 1.5*mean.
Once all of the tiles have been processes, median filter them to remove those that are anomalously high.
Build a bicubic spline to interpolate the background back to the original image size.
Evaluate the spline and return.

For more information on the SExtractor method, see:

Bertin & Arnouts (1996, AApS, 317, 393)
https://www.astromatic.net/pubsvn/software/sextractor/trunk/doc/sextractor.pdf
http://www.astr.tohoku.ac.jp/~akhlaghi/sextractor_notes.html

lsl.imaging.analysis.find_point_sources(image, threshold=4.0, fwhm=1.0, sharp=[0.2, 1.0], round=[- 1.0, 1.0], background_size=16, verbose=True)¶

Given a 2-D image, find all of the point sources in it that meet the selection criteria provided via the keywords. These are:

threshold: detection threshold in counts about the background

fwhm: source full width half max. in pixel

sharp: two-element array that defines the lower and upper bounds
on the source sharpness

round: two-element array that defines the lower and upper bounds
on the source roundness

Background estimation and removal is handled by the estimate_background() function in this module that implements a SExtractor-like method. This can be disabled by setting the ‘background_size’ keyword to 0. For details see lsl.imaging.analysis.estimate_background().

The output of this function is a five-element tuple of 1-D NumPy arrays that store information for each source. The elements are:

x: intensity-weighted center - x coordinate

y: intensity-weighted center - y coordinate

flux: peak count value - input image units

sharpness: sharpness statistic

roundness: roundness statistic

This function is based on the FIND procedure from the AstroIDL User’s Library that was written by W. Landsman (Hughes STX).

For additional information about the original IDL routines, see: http://idlastro.gsfc.nasa.gov/contents.html#C2

Self-Calibration¶

Simple self-calibration module for correlated TBW and TBN data. The supported self-calibration methods are:

phase-only

amplitude and phase

delay-only

amplitude and delay

delay/phase offset

amplitude and delay/phase offset

..versionchanged:: 0.6.3: Reworked the module to make it more versatile

..versionadded:: 0.5.5

lsl.imaging.selfcal.delay_and_phase(aa, dataSet, simSet, chan, pol, ref_ant=0, max_iter=30, amplitude=False, amplitude_cutoff=1.001, delay_cutoff=0.2, phase_cutoff=0.01, verbose=True)¶: Function to apply a delay and phase offset (and, optionally, a amplitude) self-calibration to data stored in a readUVData dictionary and a model sky stored in a lsl.sim.vis.buildSimSky dictionary for the given polarization and channel(s).

Note

If the “amplitude” keyword is set to True, a four-element tuple of self-cal’d data, gain coefficients, delays in ns, and phase offsets is returned rather than the standard three-element tuple.

lsl.imaging.selfcal.delay_only(aa, dataSet, simSet, chan, pol, ref_ant=0, max_iter=30, amplitude=False, amplitude_cutoff=1.001, delay_cutoff=0.2, verbose=True)¶: Function to apply a delay-only (and, optionally, a amplitude) self- calibration to data stored in a readUVData dictionary and a model sky stored in a lsl.sim.vis.buildSimSky dictionary for the given polarization and channel(s).

Note

If the “amplitude” keyword is set to True, a three-element tuple of self-cal’d data, gain coefficients, and delays in ns is returned rather than the standard two-element tuple.

lsl.imaging.selfcal.phase_only(aa, dataSet, simSet, chan, pol, ref_ant=0, max_iter=30, amplitude=False, amplitude_cutoff=1.001, phase_cutoff=0.01, verbose=True)¶: Function to apply a phase-only (and, optionally, a amplitude) self- calibration to data stored in a readUVData dictionary and a model sky stored in a lsl.sim.vis.buildSimSky dictionary for the given polarization and channel(s).

Note

If the “amplitude” keyword is set to True, a three-element tuple of self-cal’d data, gain coefficients, and phase offsets is returned rather than the standard two-element tuple.

Deconvolution¶

Deconvolution support for images made with lsl.imaging.utils.build_gridded_image().

lsl.imaging.deconv.clean(aa, dataDict, aipyImg, input_image=None, size=80, res=0.5, wres=0.1, pol='XX', chan=None, gain=0.2, max_iter=150, sigma=3.0, verbose=True, plot=False)¶

Given a AIPY antenna array instance, a data dictionary, and an AIPY ImgW instance filled with data, return a deconvolved image. This function uses a CLEAN-like method that computes the array beam for each peak in the flux. Thus the CLEAN loop becomes:

Find the peak flux in the residual image

Compute the systems response to a point source at that location

Remove the scaled porition of this beam from the residuals

Go to 1.

CLEAN tuning parameters:

gain - CLEAN loop gain (default 0.2)
max_iter - Maximum number of iterations (default 150)
sigma - Threshold in sigma to stop cleaning (default 3.0)

lsl.imaging.deconv.clean_sources(aa, dataDict, aipyImg, srcs, input_image=None, size=80, res=0.5, wres=0.1, pol='XX', chan=None, gain=0.1, max_iter=150, sigma=2.0, verbose=True, plot=False)¶

Given a AIPY antenna array instance, a data dictionary, an AIPY ImgW instance filled with data, and a dictionary of sources, return the CLEAN components and the residuals map. This function uses a CLEAN-like method that computes the array beam for each peak in the flux. Thus the CLEAN loop becomes:

Find the peak flux in the residual image

Compute the systems response to a point source at that location

Remove the scaled porition of this beam from the residuals

Go to 1.

This function differs from clean() in that it only cleans localized regions around each source rather than the whole image. This is intended to help the mem() function along.

CLEAN tuning parameters:

gain - CLEAN loop gain (default 0.1)
max_iter - Maximum number of iterations (default 150)
sigma - Threshold in sigma to stop cleaning (default 2.0)

lsl.imaging.deconv.lsq(aa, dataDict, aipyImg, input_image=None, size=80, res=0.5, wres=0.1, pol='XX', chan=None, gain=0.05, max_iter=150, rtol=1e-09, verbose=True, plot=False)¶

Given a AIPY antenna array instance, a data dictionary, and an AIPY ImgW instance filled with data, return a deconvolved image. This function implements a least squares deconvolution.

Least squares tuning parameters:

gain - least squares loop gain (default 0.05)
max_iter - Maximum number of iteration (default 150)
rtol - Minimum change in the residual RMS between iterations
(default 1e-9)

Post-Acquisition Beam Forming¶

New in version 0.3.

Module to allow for post-acquisition delay-and-sum beamforming with integer sample delays for TBW time series data (int_delay_and_sum) and phase-and-sum beamforming for TBN time series data (delayAndSum).

lsl.misc.beamformer.calc_delay(antennas, freq=49000000.0, azimuth=0.0, elevation=90.0)¶: Calculate the time delays for delay-and-sum beam forming a collection of stands looking in at a particular azimuth and elevation (both in degrees). A numpy array of the geometric + cable delays in seconds is returned.

Changed in version 0.5.0: Changed the computed array center to exclude stands #257 through #260

lsl.misc.beamformer.circularize(x, y, iau=True)¶: Given a 1-D Numpy array of X polarization timeseries data and Y polarization timeseries data, generate the two circular polarization. Returns a two-element tuple of L and R.

Changed in version 1.0.1: Added the ‘iau’ keyword to help define the convention of positive Stokes V. V = RCP - LCP.

New in version 1.0.0.

lsl.misc.beamformer.int_beam_shape(antennas, sample_rate=196000000.0, freq=49000000.0, azimuth=0.0, elevation=90.0, progress=False, disable_pool=False)¶: Given a list of antennas, compute the on-sky response of the delay-and-sum scheme implemented in int_delay_and_sum. A 360x90 numpy array spanning azimuth and elevation is returned.

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.

Changed in version 0.4.2: Allowed for multiple polarization data to be delayed-and-summed correctly and insured that a 2-D array is always returned (pol(s) by samples)

lsl.misc.beamformer.int_delay_and_sum(antennas, data, sample_rate=196000000.0, freq=49000000.0, azimuth=0.0, elevation=90.0)¶: Given a list of antennas and a 2-D data stream with stands enumerated along the first axis and time series samples along the second axis, delay and sum the data stream into one beam. The delays applied are integer sample delays. Return a 1-D numpy array of the time series data associated with the formed beam.

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.

lsl.misc.beamformer.phase_and_sum(antennas, data, sample_rate=196000000.0, central_freq=49000000.0, azimuth=0.0, elevation=90.0)¶: Given a list of antennas and a data stream of the form stands x times, delay and sum the data stream into one beam. Return a 1-D numpy array of the time series data associated with the formed beam.

lsl.misc.beamformer.phase_beam_shape(antennas, sample_rate=196000000.0, central_freq=49000000.0, azimuth=0.0, elevation=90.0, progress=False)¶: Given a list of antennas, compute the on-sky response of the delay-and-sum scheme implemented in int_delay_and_sum. A 360x90 numpy array spanning azimuth and elevation is returned.

Changed in version 1.2.1: Removed the ‘disable_pool’ keyword since recent optimztions to the function have caused the multiprocessing.Pool feature to actually be slower than the signle-threaded version.

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.

class lsl.common.dp.SoftwareDP(mode='DRX', filter=7, central_freq=74000000.0)¶

Class to deal with processing TBW data after the fact like DP would. This provides a means to recreate any other DP output from a TBW capture for a variety of purposes. For example, a TBW file could be processed with the DRX filter 4 to create a data stream that can be correlated and imaged.

Note

Not all DP filters are supported by this class. Supported filters are:

TBN, filters 5, 6, and 7
DRX, filters 3, 4, 5, 6, and 7

Changed in version 0.5.2: Added support for beamforming using the DP FIR coefficients and renamed SoftwareDP.apply() to SoftwareDP.applyFilter().

apply_filter(time, data, disable_pool=False)¶: Process a given batch of TBW data using the current mode of operation. This function requires both an array of times (int64 in fS since the UNIX epoch) and data (1-D or 2-D). If 2-D data are given, the first dimension should be over inputs and the second over time.

Changed in version 0.5.2: Renamed SoftwareDP.apply() to SoftwareDP.applyFilter()

form_beam(antennas, time, data, course_delays=None, fine_delays=None, gains=None)¶: Process a given batch of TBW data using the provided delay and gain information to form a beam. Returns a two-element tuple, one for each beam polarization.

set_delay_firs(channel, coeffs)¶: Set the delay FIR coefficients for a particular channel to the list of lists provided (filter set by filter coefficients). If channel is 0, the delay FIR filters for all channels are set to the provided values. If channel is -1, the delay FIR filters for all channels are set to the DP default values.

set_filter(filter)¶: Set the filter code for the current mode.

set_mode(mode)¶: Set the mode of operation for the software DP instance.

set_tuning_freq(central_freq)¶: Set the tuning frequency for the current setup.

Fake Data¶

lsl.sim - Simulate various types of LWA data. The following follow DP format writers are avaliable:

tbn

drx

In addition, there are two simulation modules to generate fake data sets::

dp - generate DP-level data sets for basic signals and point source
vis - generate visibility data sets for use with the aipy module

Writers¶

New in version 0.3.

TBN¶

Python module for creating creating, validating, and writing simulated TBN frames to a file.

class lsl.sim.tbn.SimFrame(stand=None, pol=None, central_freq=None, gain=None, frame_count=None, obs_time=None, data=None)¶

Bases: lsl.reader.tbn.Frame

tbn.SimFrame extends the lsl.reader.tbn.Frame object to yield a method for easily creating DP ICD-compliant raw TBN frames. Frames created with this method can be written to a file via the methods write_raw_frame() function.

create_raw_frame()¶: Re-express a simulated TBN frame as a numpy array of unsigned 8-bit integers. Returns a numpy array if the frame is valid. If the frame is not ICD-compliant, a errors.baseSimError-type error is raised.

is_valid(raise_errors=False)¶: Check if simulated TBN frame is valid or not. Valid frames return True and invalid frames False. If the ‘raise_errors’ keyword is set, is_valid raises an error when a problem is encountered.

load_frame(tbn_frame)¶: Populate the a tbn.SimFrame object with a pre-made frame.

write_raw_frame(fh)¶: Write a simulated TBN frame to a filehandle if the frame is valid. If the frame is not ICD-compliant, a errors.baseSimError-type error is raised.

lsl.sim.tbn.frame_to_frame(tbn_frame)¶: Convert a lsl.reader.tbn.Frame object to a raw DP TBN frame.

DRX¶

Python module for creating creating, validating, and writing simulated DRX frames to a file.

class lsl.sim.drx.SimFrame(beam=None, tune=None, pol=None, decimation=None, time_offset=None, frame_count=None, obs_time=None, flags=None, data=None)¶

Bases: lsl.reader.drx.Frame

drx.SimFrame extends the lsl.reader.drx.Frame object to yield a method for easily creating DP ICD-compliant raw DRX frames. Frames created with this method can be written to a file via the methods write_raw_frame() function.

create_raw_frame()¶: Re-express a simulated DRX frame as a numpy array of unsigned 8-bit integers. Returns a numpy array if the frame is valid. If the frame is not ICD-compliant, a errors.baseSimError-type error is raised.

is_valid(raise_errors=False)¶: Check if simulated DRX frame is valid or not. Valid frames return True and invalid frames False. If the ‘raise_errors’ keyword is set, is_valid raises an error when a problem is encountered.

load_frame(drx_frame)¶: Populate the a drx.SimFrame object with a pre-made frame.

write_raw_frame(fh)¶: Write a simulated DRX frame to a filehandle if the frame is valid. If the frame is not ICD-compliant, a errors.baseSimError-type error is raised.

lsl.sim.drx.frame_to_frame(drx_frame)¶: Convert a lsl.reader.drx.Frame object to a raw DP DRX frame.

Simulators¶

Digitial Processor Data¶

New in version 0.3.

Module to simulate observations made with the DP system.

lsl.sim.dp.basic_signal(fh, stands, nframes, mode='DRX', filter=6, ntuning=2, bits=12, start_time=0, noise_strength=0.1, verbose=False)¶

Generate a collection of frames with a basic test signal for TBN and DRX. The signals for the three modes are:

TBN

noise + (sample_rate/4) kHz signal for x-pol. and noise +
(-sample_rate/4) for y-pol.

DRX

noise + (sample_rate/4) kHz signal for x-pol. and noise +
(-sample_rate/4) for y-pol. -> tuning 1
noise + (-sample_rate/3) kHz signal for x-pol. and noise +
(sample_rate/3) for y-pol. -> tuning 2

All modes need to have stands (beams in the case of DRX) and number of frames to generate. The TBN and DRX frames need the ‘filter’ keyword set to specify the filter width. In addition, the ‘stands’ argument is interpreted as beam numbers for DRX.

Changed in version 0.4.4: Added the noise_strength keyword to control how much noise is added to the data.

Changed in version 2.0.0: Removed support for generating TBW data.

lsl.sim.dp.point_source(fh, stands, src, nframes, mode='TBN', central_freq=49000000.0, filter=7, bits=12, start_time=0, phase_center='z', noise_strength=0.1, verbose=False)¶

Generate a collection of frames with a point source signal for TBN. The point source is specified as a aipy.src object.

All modes need to have stands (beams in the case of DRX) and number of frames to generate. The TBN frames need the `filter’ keyword set to specify the filter width.

Changed in version 0.4.4: Added the noise_strength keyword to control how much noise is added to the data.

Changed in version 2.0.0: Removed support for generating TBW data.

Visibility Data¶

Module for generating simulated arrays and visibility data. The chief functions of this module are:

build_sim_array

given a station object, a list of stands, and a list of frequencies, build a AIPY AntennaArray-like object. This module can also generate AntennaArray objects with positional errors by setting the ‘pos_error’ keyword to a positive value.

build_sim_data

given a SimArray and a list of aipy.src sources, build up a collection of visibilities for a given set of Julian dates

scale_data

given a dictionary of simulated visibilities from build_sim_data, apply antenna-based gains and delays to the visibilities

shift_data

given a dictionary of simulated visibilities from build_sim_data, shift the uvw coordinates of the visibilities. .. note:

This only changes the uvw values and does not phase-shift the data.

The format of the is descrined in the lsl.imaging.data module.

In addition to simulation functions, this module includes buildGriddedImage which takes a dictionary of visibilities and returns and aipy.im.ImgW object.

Changed in version 0.3.0: This module was formerly called lsl.sim.sim

Changed in version 0.5.0: Moved buildGriddedImage to the lsl.imaging.utils module.

Changed in version 1.0.1: Switched over to a new C-based simulation package

Changed in version 1.0.2: Added in a function, add_baseline_noise, to help bring noise into the simulations

Changed in version 1.0.3: Moved the calculateSEFD function into lsl.misc.rfutils Changed the meaning of the force_gaussian parameter of the build_sim_array() function to be the Gaussian full width at half maximum in degrees

class lsl.sim.vis.Antenna(x, y, z, beam, phsoff=[0.0, 0.0], bp_r=array([1]), bp_i=array([0]), amp=1, pointing=0.0, 1.5707963267948966, 0, stand=0, **kwargs)¶

Modification to the aipy.amp.Antenna class to also store the stand ID number in the Antenna.stand attribute. This also add a getBeamShape attribute that pulls in the old vis.getBeamShape function.

bm_response(top, pol='x')¶: Return response of beam for specified polarization.

Note

This differs from the AIPY implementation in that the LWA X-pol. is oriented N-S, not E-W.

Note

This function also accepts two and three-dimensions arrays of topocentric coordinates, similar to what img.ImgW.get_top() produces, and computes the beam response at all points.

get_beam_shape(pol='x')¶: Return a 360 by 90 by nFreqs numpy array showing the beam pattern of a particular antenna in the array. The first two dimensions of the output array contain the azimuth (from 0 to 359 degrees in 1 degree steps) and altitude (from 0 to 89 degrees in 1 degree steps).

class lsl.sim.vis.AntennaArray(*args, **kwargs)¶

Modification to the aipy.ant.AntennaArray class to add a function to retrieve the stands stored in the AntennaArray.ants attribute. Also add a function to set the array time from a UNIX timestamp.

Changed in version 1.0.1: Added an option to set the ASP filter for simulation proposes. This updates the bandpasses used by AIPY to include the antenna impedance mis-match and the mean ARX response.

gen_phs_fast(src, i, j, mfreq=0.15, ionref=None, srcshape=None, resolve_src=False, u=None, v=None, w=None)¶: Return phasing that is multiplied to data to point to src - fast.

gen_uvw_fast(i, j, src='z', w_only=False, map=None)¶: Compute uvw coordinates of baseline relative to provided RadioBody, or ‘z’ for zenith uvw coordinates. If w_only is True, only w (instead of (u,v,w) will be returned) - fast.

get_baseline_fast(i, j, src='z', map=None)¶: Return the baseline corresponding to i,j in various coordinate projections: src=’e’ for current equatorial, ‘z’ for zenith topocentric, ‘r’ for unrotated equatorial, or a RadioBody for projection toward that source - fast.

get_stands()¶: Return a numpy array listing the stands found in the AntennaArray object.

set_asp_filter(filter='split')¶

Update the bandpasses for the antennas to include the effect of the antenna impedance mis-match (IMM) and the mean LWA1 ARX response.

Valid filters are:

split
full
reduced
split@3MHz
full@3MHz
none

None is a special case where both the IMM and ARX response are removed, i.e., the bandpass is unity for all frequencies.

Changed in version 1.2.1: Added support for the ‘split@3MHz’ and ‘full@3MHz’ filters at LWA-SV.

New in version 1.0.1.

set_unixtime(timestamp)¶: Set the array time using a UNIX timestamp (epoch 1970).

sim(i, j, pol='xx')¶

Simulate visibilities for the specified (i,j) baseline and polarization. sim_cache() must be called at each time step before this will return valid results.

This function differs from aipy.amp.AntennaArray.sim in the fact that ionref and srcshape are both None in the call to gen_phs and that resolve_src is set to False.

class lsl.sim.vis.BeamAlm(freqs, lmax=8, mmax=8, deg=7, nside=64, coeffs={})¶

AIPY-based representation of a beam model where each pointing has a response defined as a polynomial in frequency, and the spatial distributions of these coefficients decomposed into spherical harmonics.

This differs from the AIPY version in that the response() method accepts two and three-dimensions arrays of topocentric coordinates, similar to what aipy.img.ImgW.get_top() produces, and computes the beam response at all points.

response(top)¶: Return beam response across active band for specified topocentric coordinates (x=E,y=N,z=UP). x,y,z may be multiple coordinates. Returns ‘x’ pol (rotate pi/2 for ‘y’).

Note

This function also accepts two and three-dimensions arrays of topocentric coordinates, similar to what aipy.img.ImgW.get_top() produces, and computes the beam response at all points

class lsl.sim.vis.RadioEarthSatellite(tle, tfreq, tpower=0.0, tbw=1000000.0, ionref=0.0, 0.0)¶

Implement a aipy.amp.RadioBody-lime simulation object for an Earth- orbiting satellite using a two-line element set.

compute(observer)¶: Update coordinates relative to the provided observer. Must be called at each time step before accessing information.

get_crds(crdsys, ncrd=3)¶: Return the coordinates of this location in the desired coordinate system (‘eq’,’top’) in the current epoch. If ncrd=2, angular coordinates (ra/dec or az/alt) are returned, and if ncrd=3, xyz coordinates are returned.

get_jys()¶: Return the fluxes vs. freq that should be used for simulation.

update_jys(afreqs)¶: Update fluxes relative to the provided observer. Must be called at each time step before accessing information.

lsl.sim.vis.add_baseline_noise(dataSet, SEFD, tInt, bandwidth=None, efficiency=1.0)¶

Given a lsl.imaging.data.VisibilityDataSet object of visibilities, an SEFD or array SEFDs in Jy, and an integration time in seconds, add noise to the visibilities assuming that the “weak source” limit.

This function implements Equation 9-15 from Chapter 9 of “Synthesis Imaging in Radio Astronomy II”.

New in version 1.0.2.

lsl.sim.vis.build_sim_array(station, antennas, freq, jd=None, pos_error=0.0, force_flat=False, force_gaussian=False, verbose=False)¶

Build a AIPY AntennaArray for simulation purposes. Inputs are a station object defined from the lwa_common module, a numpy array of stand numbers, and a numpy array of frequencies in either Hz of GHz. Optional inputs are a Julian Date to set the array to and a positional error terms that perturbs each of the stands in x, y, and z. The output of this module is an AIPY AntennaArray object.

The shape of the antenna response is either flat (gain of 1 in all directions), modeled by a 2-D Gaussian with the specified full width at half maximum in degrees, or modeled by a collection of spherical harmonics that are polynomials in frequency. The spherical harmonics are used if the file ‘beam_shape.npz’ is found in the current directory.

Changed in version 1.0.3: Changed the meaning of the force_gaussian parameters so that the Gaussian full width at half maximum in degrees is passed in.

Changed in version 1.0.1: Moved the simulation code over from AIPY to the new _simFast module. This should be much faster but under the caveats that the bandpass and antenna gain patterns are the same for all antennas. This should be a reasonable assumption for large-N arrays.

Added an option to use a 2-D Gaussian beam pattern via the force_gaussian keyword.

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.sim.vis.build_sim_data(aa, srcs, pols=['xx', 'yy', 'xy', 'yx'], jd=None, chan=None, phase_center='z', baselines=None, mask=None, flat_response=False, resolve_src=False, verbose=False)¶

Given an AIPY AntennaArray object and a dictionary of sources from aipy.src.get_catalog, returned a lsl.imaging.data.VisibilityDataSet object of simulated data taken at zenith. Optinally, the data can be masked using some referenced (observed) data set or only a specific sub-set of baselines.

Changed in version 1.0.1: * Added a ‘flat_response’ keyword to make it easy to toggle on and off the spectral and spatial response of the array for the simulation * Added a ‘resolve_src’ keyword to turn on source resolution effects

..versionchanged:: 0.4.0: Added the ‘pols’ keyword to only compute certain polarization components

lsl.sim.vis.scale_data(dataSet, amps, delays, phase_offsets=None)¶

Apply a set of antenna-based real gain values and phase delays in ns to a lsl.imaging.data.VisibilityDataSet object. Returned the new scaled and delayed VisibilityDataSet.

..versionchanged:: 0.6.3: Added a keyword so that phase offsets (in radians) can also be specified
..versionchanged:: 0.4.0: The delays are now expected to be in nanoseconds rather than radians.

lsl.sim.vis.shift_data(dataSet, aa)¶: Shift the uvw coordinates in one lsl.imaging.data.VisibilityDataSet object to a new set of uvw coordinates that correspond to a new AntennaArray object. This is useful for looking at how positional errors in the array affect the data.

Miscellaneous¶

RF Antenna Parameters¶

A collection of utilities to help convert RF engineering/communications terms into radio astronomy terms. This module is geared toward taking antenna parameters in dBi or dBd and converting them into meaningful RA gains in K/Jy and then using those to get a system equivalent flux density.

New in version 1.0.3.

lsl.misc.rfutils.Jy_to_dBm(flux, bandwidth, gain)¶

Convert a flux density in Jy into a received signal strength in dBm under the assumptions of:

signal bandwidth in Hz

antenna gain in K/Jy

lsl.misc.rfutils.calculate_effective_area(gain)¶: Given the gain of an antenna in K/Jy, calculate the effective collecting area in square meters.

lsl.misc.rfutils.calculate_sefd(Tsys, gain=None, area=None, efficiency=None)¶

Given a variety of parameters, calculate the system equivalent flux density in Jy for an antenna. The parameters are:

Tsys - system temperature in K - required

gain - antenna gain in K/Jy - optional

area - antenna collecting area in m^2 - optional

efficiency - aperture efficiency - optional

Of the optional parameters either ‘gain’ needs to be supplied or both ‘area’ and ‘efficiency’.

lsl.misc.rfutils.dBd_to_dBi(dBd)¶: Convert an antenna gain in dBb (gain relative to the maximum gain of a half-wave dipole) into a gain in dBi (gain relative to an isotropic antenna).

lsl.misc.rfutils.dBd_to_dBi(dBd)¶: Convert an antenna gain in dBb (gain relative to the maximum gain of a half-wave dipole) into a gain in dBi (gain relative to an isotropic antenna).

lsl.misc.rfutils.dBd_to_gain(dBd, frequency)¶: Convert an antenna gain in dBd (gain relative to the maximum gain of a half-wave dipole) at a particular frequency in Hz into a gain in K/Jy

lsl.misc.rfutils.dBi_to_gain(dBi, frequency)¶: Convert an antenna gain in dBi (gain relative to an isotropic antenna) at a particular frequency in Hz into a gain in K/Jy.

lsl.misc.rfutils.dBm_to_Jy(dBm, bandwidth, gain)¶

Convert a received signal strength in dBm into a flux density in Jy under the assumptions of:

signal bandwidth in Hz

antenna gain in K/Jy

lsl.misc.rfutils.gain_to_dBd(gain, frequency)¶: Convert an antenna gain in K/Jy at a particular frequency in Hz into a gain in dBd (gain relative to the maximum gain of a half-wave dipole).

lsl.misc.rfutils.gain_to_dBi(gain, frequency)¶: Convert an antenna gain in K/Jy at a particular frequency in Hz into a gain in dBi (gain relative to an isotropic antenna).

Simulated Stand Response¶

This module contains a set of convenience functions to parse the output of NEC2, modify the input (.nec) file, and rerun NEC as necessary. NEC2 is the Numerical Electromagnetics Code, developed at LLNL. The version of NEC2 this code currently assumes is here.

Several NEC files are included with the LSL distribution for modeling the dipoles. See the README.NEC file included in the LSL data directory for more information about what is included.

class lsl.sim.necutils.NECImpedance(necname)¶

NECImpedance: Python class to read an array of impedance values from a NEC2 .out file The .nec file should loop over a range of frequencies with an FR card like this:

FR 0 91 0 0 10.0 1.0

The RP card should be minimal to keep the runtime and output file size from growing huge. For example:

RP 0,91,1,1000,0.,0.,1.0,1.0

class lsl.sim.necutils.NECPattern(necname, freq, rerun=True)¶

NECPattern: Python class to read the pattern from a NEC2 .out file. Note that the .nec file should have an RP or EX card to run over the full pattern, like this:

RP 0,91,360,1000,0.,0.,1.0,1.0,0.

The FR card should be a simple single frequency run:

FR 0,1,0,0,74.0,1

Changed in version 1.2.0: Added a new “antenna_pat_complex attribute to store the complex antenna pattern

lsl.sim.necutils.calculate_ime(necname, myfreqs=None, zpre=100)¶: Compute the impedance mismatch efficiency (IME), for a given NEC run and write out the results in a file. Assumes a default preamplifier input impedance of 100 ohms, unless overridden by the zpre keyword argument. Returns the frequencies calculated by NEC, unless myfreqs is set, in which case it interpolates onto that frequency grid.

lsl.sim.necutils.change_nec_freq(necname, freq)¶: Modify the FR card in a NEC input file to run at freq.

lsl.sim.necutils.close_to(x, y, epsilon=0.005)¶: Return True if two numbers are within a specified fractional, not absolute, tolerance of each other. Tolerance epsilon is a keyword parameter with a default of 0.005.

lsl.sim.necutils.open_and_get_nec_freq(fname)¶: Open a NEC output file and return a tuple containing the open file object and the first frequency found in the file (MHz).

lsl.sim.necutils.which_nec4()¶: Return the path to the nec4d executable if it can be found in the current path. None otherwise. This is useful for making sure that NEC is installed before trying to run something.

Ionospheric and Geomagnetic Field Models¶

New in version 1.1.0.

A collection of utilities for retrieving parameters that may be relevant for ionospheric corrections.

lsl.misc.ionosphere.compute_magnetic_declination(Bn, Be, Bz)¶: Given the topocentric output of get_magnetic_field(), compute and return the magnetic declination (deviation between magnetic north and true north) in degrees.

Note

The declination is poorly defined (NaN) around the magnetic poles where the horizontal field strength is less than 100 nT.

lsl.misc.ionosphere.compute_magnetic_inclination(Bn, Be, Bz)¶: Given the topocentric output of get_magnetic_field(), compute and return the magnetic inclination or magnetic dip (angle between the magnetic field and the horizontal) in degrees.

lsl.misc.ionosphere.get_ionospheric_pierce_point(site, az, el, height=450000.0, verbose=False)¶: Given a site and a pointing direction (azimuth and elevation in degrees), compute the location of the ionospheric pierce point. Since the height assumed for the ionosphere is model-dependent the ‘height’ keyword sets the elevation to use in meters. Returns a three-element tuple of latitude (degrees, North is positive), longitude (degrees, East is positive), and elevation (meters).

lsl.misc.ionosphere.get_magnetic_field(lat, lng, elev, mjd=None, ecef=False)¶: Given a geodetic location described by a latitude in degrees (North positive), a longitude in degrees (West negative), an elevation in meters and an MJD value, compute the Earth’s magnetic field in that location and return a three-element tuple of the magnetic field’s components in nT. By default these are in topocentric coordinates of (North, East, Up). To return values in ECEF, set the ‘ecef’ keyword to True. If the MJD file is None, the current time is used.

Note

The convention used for the topocentric coordinates differs from what the IGRF uses in the sense that the zenith direction points up rather than down.

lsl.misc.ionosphere.get_tec_value(mjd, lat=None, lng=None, include_rms=False, timeout=120, type='IGS')¶: Given an MJD value and, optionally, a latitude and longitude in degrees, compute the TEC value in TECU above that location using data from the IGS or CODE (depending on the value of the ‘type’ keyword). If the ‘include_rms’ keyword is set to True, also return the RMS in the TEC value.

Conversion Helper Functions for argparse¶

New in version 1.2.4.

Module that provides argparse-compatible conversion functions for a variety of value formats, including:

positive integers,

ephem.hours instances, and

lists of integers from a comma-separated list.

New in version 1.2.4.

lsl.misc.parser.csv_baseline_list(string)¶: Convert a comma-separated list of baslines pairs into a list of baseline pairs. Baseline pairs are defined as ‘antenna1-antenna2’ where ‘antenna1’ and ‘antenna2’ are both integers or ranges denoted by the ‘~’ character.

lsl.misc.parser.csv_degrees_list(string)¶: Convert a comma-separated list of ‘sDD[:MM[:SS.[SSS]]]’ string into a list of ephem.degrees instances.

lsl.misc.parser.csv_hostname_list(string)¶

Convert a comma-separated list of IPv4 addresses/hostnames into a list IPv4 addresses/hostnames. This function support indexing with the ‘~’ character so long as:

the character is in any one of the IPv4 bytes or

the character is at the end of a hostname which ends with a number

lsl.misc.parser.csv_hours_list(string)¶: Convert a comma-separated list of ‘HH[:MM[:SS.[SSS]]]’ string into a list of ephem.hours instances.

lsl.misc.parser.csv_int_list(string)¶: Convert a comma-separated list of integers into a list of integers. This function also allows for ranges to be specifed using the ‘~’ character. This formatting converts ‘start~stop’ to ‘range(start, stop+1)’.

lsl.misc.parser.date(string)¶: Convert a data as either a YYYY[-/]MM[-/]DD or MJD string into a YYYY/MM/DD string.

lsl.misc.parser.degrees(string)¶: Convert a ‘sDD[:MM[:SS[.SSS]]]’ string into an ephem.degrees instance.

lsl.misc.parser.frequency(string)¶

Convert a frequency to a float Hz value. This function accepts a variety of string formats:

pure float values are intepreted to be in MHz (45.0 -> 45e6)

number/unit pairs are allowed so long as they are in:

[prefix]m, A, or ang for wavelength and

[prefix]Hz for frequency

lsl.misc.parser.frequency_range(string)¶

Convert a frequency to a float Hz value. This function accepts a variety of string formats:

a ‘number~number’ is interpretted as a range in MHz

a ‘number/unit~number/unit’ is converted to a range in Hz

Note

For ranges, a two-element list is returned where the first value is less than the second.

lsl.misc.parser.hours(string)¶: Convert a ‘HH[:MM[:SS[.SSS]]]’ string into an ephem.hours instance.

lsl.misc.parser.mjd(string)¶: Convert a data as either a YYYY[-/]MM[-/]DD or MJD string into an integer MJD.

lsl.misc.parser.mpm(string)¶: Covnert a time as HH:MM:SS[.SSS] or MPM string into an MPM integer.

lsl.misc.parser.positive_float(string)¶: Convert a string to a positive (>0.0) float.

lsl.misc.parser.positive_int(string)¶: Convert a string to a positive (>0) integer.

lsl.misc.parser.positive_or_zero_float(string)¶: Convert a string to a positive (>=0.0) float.

lsl.misc.parser.positive_or_zero_int(string)¶: Convert a string to a positive (>=0) integer.

lsl.misc.parser.time(string)¶: Covnert a time as HH:MM:SS[.SSS] or MPM string into a HH:MM:SS.SSSSSS string.

lsl.misc.parser.wavelength(string)¶

Convert a wavelength to a float m value. This function accepts a variety of string formats:

pure float values are intepreted to be in m (45.0 -> 45.0)

number/unit pairs are allowed so long as they are in:

[prefix]m, AA, or Angstrom for wavelength and

[prefix]Hz for frequency

lsl.misc.parser.wavelength_range(string)¶

Convert a wavelength to a float m value. This function accepts a variety of string formats:

a ‘number~number’ is interpretted as a range in m

a ‘number/unit~number/unit’ is converted to a range in m

Note

For ranges, a two-element list is returned where the first value is less than the second.

Included Scripts¶

General Utilities¶

gatherDebugging.py

Description: Script to gather information about the Pytho/numpy/LSL install to help with troubleshooting.
Usage: gatherDebugging.py
Options: None

lslTelemetry.py

Description

Script to change the LSL telemetry setting.

Usage

lslTelemetry.py [options]

Options

-h, --help: Display this help information
-e, --enabled: Enable telemetry for LSL
-d, --disable: Disable telemetry for LSL
-k, --key: Show install identification key

makeWisdom.py

Description: Build LSL-specific FFTW wisdom and save it to a file within the LSL distribution.
Usage: makeWisdom.py
Options: None

updateLSLSSMIF.py

Description

Update the internal LWA1 SSMIF used by LSL.

Usage

updateLSLSSMIF.py [options]

Options

-h, --help: Display this help information
-u, --update: Update the default LWA1 SSMIF
-r, --revert: Revert the default LWA1 SSMIF to an older version

astroevents.py

Description: Application to display rise, transit, and set times for various astronomical sources from LWA-1 for the current date.
Usage: astroevents.py
Options: None

astrostatus.py

Description

Application to calculate real-time ephemeris for a LWA site.

Usage

astrostatus.py [options]

Options

-h, --help: show this help message and exit
-s SITE, --site=SITE: site name (default LWA-1)

driftcurve.py

Description

Generate a drift curve for a dipole at LWA-1 observing at a given frequency in MHz.

Usage

driftcurve.py [OPTIONS]

Options

-h, --help: Display this help information
-f, --freq: Frequency of the observations in MHz (default = 74 MHz)
-p, --polarization: Polarization of the observations (NS or EW; default = EW)
-l, --lf-map: Use LF map instead of GSM
-t, --time-step: Time step of simulations in minutes (default = 10)
-x, --do-plot: Plot the driftcurve data
-v, --verbose: Run driftcurve in vebose mode

getIonosphericRM.py

Description

Estimate the ionospheric contribution to the RM for an observation using the IGS final product and the IGRF.

Usage

getIonosphericRM.py [options] RA Dec Start Stop

RA: J2000 right ascension in HH:MM:SS[.SSS]

Dec: J2000 declination in sDD:MM:SS[.SSS]

Start: YYYY/MM/DD HH:MM:SS start time in UTC

Stop: YYYY/MM/DD HH:MM:SS stop time in UTC

Options

-h, --help: Display this help information
-n, --n-samples: Number of samples to take between the start and stop times (default = 11)

lwa_cat_view.py

Description

Simple LWDA astronomical source catalogue display application.

Usage

lwa_cat_view.py [options]

Options

-h, --help: show this help message and exit
-s SITE, --site=SITE: site name (default LWDA)
-p PERIOD, --period=PERIOD: update period in seconds (default 5)

inspectTarball.py

Description: Given a MCS metadata tarball, print out details of the associated observations.
Usage: inspectTarball.py metaData
Options: None

plotAntenna.py

Description

Plot the relative dipole response for both polarizations of an isolated LWA-1 antenna at a particular frequency.

Usage

plotAntenna.py [OPTIONS]

Options

-h, --help: Display this help information
-f, --freq: Frequency of the observations in MHz (default = 74 MHz)
-v, --verbose: Run plotAntenna in vebose mode

plotStands.py

Description

Plot the x, y, and z locations of stands at LWA-1. Also, mark and label particular stands, if requested.

Usage

plotStands.py [OPTIONS] [stand1 [stand2 […]]]

Options

-h, --help: Display this help information
-m, --metadata: Name of SSMIF or metadata tarball file to use for mappings
-l, --label: Label the stands with their ID numbers (default = No)
-v, --verbose: Run plotStands in vebose mode
-o, --output: Filename to save the plot to (default = do not save)

plotUVCoverage.py

Description

Randomly select 20 antennae from LWA-1 and plot the uv-plane coverage for a zenith snapshot and the expected beam. Alternatively, select some FRACTION of the stands with installed FEEs to use or use the specified list of stands.

Usage

plotUVCoverage.py [FRACTION | STAND LIST]

Options

-h, --help: Display this help information
-f, --frequency: Frequency in MHz to compute the uv coverage (default 50 MHz)
-m, --metadata: Name of SSMIF or metadata tarball file to use for mappings
-o, --output: Filename to save the plot to (default = do not save)

Data Reading and Writing¶

splitTBN.py

Description

Split a TBN file containing multiple seconds into several files

Usage

splitTBN.py [options] file

Options

-h, --help: Display this help information
-c, --count: Number of seconds to keep
-o, --offset: Number of seconds to skip before splitting
-d, --date: Label the split files with a date rather than a squence number

Note

This script does not use a lsl.reader.buffer buffer to try to re-order or verify all packets and simply splits files based on size.

splitDRX.py

Description

Split a DRX file containing multiple seconds into several files

Usage

splitDRX.py [options] file

Options

-h, --help: Display this help information
-c, --count: Number of seconds to keep
-o, --offset: Number of seconds to skip before splitting
-d, --date: Label the split files with a date rather than a squence number

splitSession.py

Description: Given a MCS metadata tarball and a session DRX recording, split the session recording into the individual observations.
Usage: splitSession.py metaData data
Options: None

plotMapper.py

Description: Read and plot the NOSTA_MAPPER table in a FITS IDI file writen by lsl.writer.fitsidi if it exists.
Usage: plotMapper.py file
Options: None

Data Analysis¶

tbwSpectra.py

Description

Given a TBW file, plot the time averaged spectra for each digitizer input.

Usage

tbwSpectra.py [OPTIONS] file

Options

-h, --help: Display this help information
-m, --metadata: Name of SSMIF or metadata tarball file to use for mappings
-t, --bartlett: Apply a Bartlett window to the data
-b, --blackman: Apply a Blackman window to the data
-n, --hanning: Apply a Hanning window to the data
-q, --quiet: Run tbwSpectra in silent mode
-l, --fft-length: Set FFT length (default = 4096)
-g, --gain-correct: Correct signals for the cable losses
-s, --stack: Stack spectra in groups of 6 (if ‘-g’ is enabled only)
-d, --disable-chunks: Display plotting chunks in addition to the global average
-o, --output: Output file name for spectra imag

Warning

tbwSpectra.py currently assumed that the system it is running on has enough memory to read in a full TBW capture. Due to data representation and processing overheads this amounts to about 16 GB.

tbnSpectra.py

Description

Given a TBN file, plot the time averaged spectra for each digitizer input.

Usage

tbnSpectra.py [OPTIONS] file

Options

-h, --help: Display this help information
-m, --metadata: Name of SSMIF or metadata tarball file to use for mappings
-t, --bartlett: Apply a Bartlett window to the data
-b, --blackman: Apply a Blackman window to the data
-n, --hanning: Apply a Hanning window to the data
-s, --skip: Skip the specified number of seconds at the beginning of the file (default = 0)
-a, --average: Number of seconds of data to average for spectra (default = 10)
-q, --quiet: Run tbwSpectra in silent mode
-l, --fft-length: Set FFT length (default = 4096)
-d, --disable-chunks: Display plotting chunks in addition to the global average
-o, --output: Output file name for spectra image

drxSpectra.py

Description

Given a DRX file, plot the time averaged spectra for each beam output.

Usage

drxSpectra.py [OPTIONS] file

Options

-h, --help: Display this help information
-t, --bartlett: Apply a Bartlett window to the data
-b, --blackman: Apply a Blackman window to the data
-n, --hanning: Apply a Hanning window to the data
-s, --skip: Skip the specified number of seconds at the beginning of the file (default = 0)
-a, --average: Number of seconds of data to average for spectra (default = 10)
-q, --quiet: Run tbwSpectra in silent mode
-l, --fft-length: Set FFT length (default = 4096)
-d, --disable-chunks: Display plotting chunks in addition to the global average
-o, --output: Output file name for spectra image

drSpecSpectra.py

Description

Given a DR spectrometer file, plot the time averaged spectra for each beam output.

Usage

drSpecSpectra.py [OPTIONS] file

Options

-h, --help: Display this help information
-s, --skip: Skip the specified number of seconds at the beginning of the file (default = 0)
-a, --average: Number of seconds of data to average for spectra (default = 10)
-q, --quiet: Run drSpecSpectra in silent mode
-d, --disable-chunks: Display plotting chunks in addition to the global average
-o, --output: Output file name for spectra image

correlateTBW.py

Description

Cross-correlate data in a TBW file

Usage

correlateTBW.py [OPTIONS] file

Options

-h, --help: Display this help information
-m, --metadata: Name of SSMIF or metadata tarball file to use for mappings
-l, --fft-length: Set FFT length (default = 2048)
-q, --quiet: Run correlateTBW in silent mode
-x, --xx: Compute only the XX polarization product (default)
-y, --yy: Compute only the YY polarization product
-2, --two-products: Compute both the XX and YY polarization products

correlateTBN.py

Description

Example script that reads in TBN data and runs a cross-correlation on it. The results are saved in the Miriad UV format.

Usage

correlateTBN.py [OPTIONS] file

Options

-h, --help: Display this help information
-m, --metadata: Name of SSMIF or metadata tarball file to use for mappings
-f, --fft-length: Set FFT length (default = 256)
-t, --avg-time: Window to average visibilities in time (seconds; default = 6 s)
-s, --samples: Number of average visibilities to generate (default = 10)
-o, --offset: Seconds to skip from the beginning of the file
-q, --quiet: Run correlateTBN in silent mode
-x, --xx: Compute only the XX polarization product (default)
-y, --yy: Compute only the YY polarization product
-2, --two-products: Compute both the XX and YY polarization products
-4, --four-products: Compute all for polariation products: XX, YY, XY, and YX.

possm.py

Description: Script that takes a FITS IDI file and mimics the AIPS task POSSM by plotting average cross-power spectra for all baselines in the FITS IDI file.
Usage: possm.py file
Options: None

imageIDI.py

Description

Script that takes a FITS IDI file and images the data.

Usage

imageIDI.py file

Options

-h, --help: Display this help information
-1, --freq-start: First frequency to image in MHz (Default = 10 MHz)
-2, --freq-stop: Last frequency to image in MHz (Default = 88 MHz)
-s, --dataset: Data set to image (Default = All)
-m, --uv-min: Minimun baseline uvw length to include (Default = 0 lambda at midpoint frequency)
-n, --no-labels: Disable source and grid labels
-g, --no-grid: Disable the RA/Dec grid

Tutorials¶

Advanced¶

C Extensions¶

Warning

The modules documented before are compiled C extensions and are subject to change. It is recommended that users use the standard modules detailed in the previous sections over directly using these modules.

Go-Fast! Readers¶

Go Fast! (TM) - TBW, TBN, DRX, DR Spectrometer, and VDIF readers written in C

exception lsl.reader._gofast.EOFError¶: Exception raised when a reader encounters the end-of-file while reading.

exception lsl.reader._gofast.SyncError¶: Exception raised when a reader encounters an error with one or more of the four sync. words.

lsl.reader._gofast.read_cor()¶: Function to read in a single COR frame (header+payload) and store the contents as a Frame object.

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

New in version 1.2.0.

lsl.reader._gofast.read_drspec()¶: Function to read in a DR spectrometer header structure and data and return a drspec.Frame instance.

Note

This function normalizes the spectra by the number of relevant fills. For 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.

lsl.reader._gofast.read_drx()¶: Function to read in a single DRX frame (header+payload) and store the contents as a Frame object.

lsl.reader._gofast.read_tbf()¶: Function to read in a single TBW frame (header+data) and store the contents as a Frame object.

New in version 1.2.0.

lsl.reader._gofast.read_tbn()¶: Function to read in a single TBN frame (header+payload) and store the contents as a Frame object.

lsl.reader._gofast.read_tbw()¶: Function to read in a single TBW frame (header+payload) and store the contents as a Frame object.

lsl.reader._gofast.read_vdif()¶: Function to read in a single VDIF frame (header+payload) and store the contents as a Frame object.

exception lsl.reader._gofast.EOFError¶: Exception raised when a reader encounters the end-of-file while reading.

exception lsl.reader._gofast.SyncError¶: Exception raised when a reader encounters an error with one or more of the four sync. words.

Power Spectral Density Calculation¶

Linear Polarization¶

Extension to take timeseries data and convert it to the frequency domain.

The functions defined in this module are:

FPSD - FFT and integrate function for computing a series of overlapped
Fourier transforms for a real-valued (TBW) or complex-valued (TBN and DRX) signals from a collection of stands all at once.
PFBPSD - Similar to FPSD, but using a 4-tap + Hanning windowed polyphase
filter bank.

See the inidividual functions for more details.

Changed in version 1.3.0: Merged FPSDR and FPSDC into the new FPSD

Changed in version 1.0.1: Removed the polyphase filterbank versions of the four core functions.

lsl.correlator._spec.FPSD()¶

Perform a series of Fourier transforms with windows on data to get the PSD.

Input arguments are:

signals: 2-D numpy (stands by samples) array of data to FFT

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
window: Callable Python function for generating the window or None for
no window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLevel to zero disables time-domain blanking

Outputs:

psd: 2-D numpy.double (stands by channels) of PSD data

lsl.correlator._spec.PFBPSD()¶

Perform a series of polyphase filter bank transforms (4-tap plus a Hanning window) on data to get the PSD.

Input arguments are:

signals: 2-D numpy (stands by samples) array of data to FFT

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
window: Callable Python function for generating the window or None for
no window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLevel to zero disables time-domain blanking

Outputs:

psd: 2-D numpy.double (stands by channels) of PSD data

Stokes Parameters¶

Extension to take X and Y timeseries data and create the four Stokes parameters.

The functions defined in this module are:

FPSDR - FFT and integrate function for computing a series of overlapped
Fourier transforms for a real-valued (TBW) or complex-valued (TBN and DRX) signals from a collection of stands all at once.
PFBPSD - Similar to FPSD, but using a 4-tap + Hanning windowed polyphase
filter bank.
XEngine3 - Similar to XEngine2, but works with all linear polarization products at
once to compute all four Stokes parameters.

Also included is an X-Engine for use with the lsl.correlator._core module to perform cross-correlations for the stokes parameters.

See the inidividual functions for more details.

lsl.correlator._stokes.FPSD()¶

Perform a series of Fourier transforms with windows on data to get the PSD for the four Stokes parameters: I, Q, U, and V.

Input arguments are:

signals: 2-D numpy.int16 (stands by samples) array of data to FFT

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
window: Callable Python function for generating the window or None for
no window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLevel to zero disables time-domain blanking

Outputs:

psd: 3-D numpy.double (Stokes parameter (I,Q,U,V) by stands by channels)
of PSD data

lsl.correlator._stokes.PFBPSD()¶

Perform a series of polyphase filter bank transforms (4-tap plus a Hanning window) on data to get the PSD for the four Stokes parameters: I, Q, U, and V.

Input arguments are:

signals: 2-D numpy.int16 (stands by samples) array of data to FFT

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
window: Callable Python function for generating the window or None for
no window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLevel to zero disables time-domain blanking

Outputs:

psd: 3-D numpy.double (Stokes parameter (I,Q,U,V) by stands by channels)
of PSD data

lsl.correlator._stokes.XEngine3()¶

Perform all XMACs for a data stream out of the F engine using OpenMP that creates the four Stokes parameters: I, Q, U, and V.

Input arguments are:

fsignalsX: 3-D numpy.complex64 (stand by channels by FFT_set) array of FFTd
data from an F engine.
fsignalsY: 3-D numpy.complex64 (stand by channels by FFT_set) array of FFTd
data from an F engine.
sigValidX: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the first signal.
sigValidY: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the second signal.

Ouputs:

visibility: 3-D numpy.cdouble (Stokes parameter (I,Q,U,V by baseline by
channel) array of cross-correlated and averaged visibility data.

FX Correlator Core¶

C-based F and X engines for the LWA software FX correlator. These function are meant to provide an alternative to the lsl.correlator.fx.correlate function and provide a much-needed speed boost to cross-correlation.

The function defined in this module are:

FEngine - F-engine for computing a series of overlapped Fourier transforms with
delay corrections for a real-valued (TBW) or complex valued (TBN or DRX) signals from a collection of stands all at once.
PFBEngine - Similar to FEngine, but using a 4-tap + Hanning windowed polyphase
filter bank.
XEngine2 - Cross multiply a single polarization stream created by FEngine or
PFBEngine
XEngine3 - Similar to XEngine2, but works with all linear polarization products at
once.

See the inidividual functions for more details.

lsl.correlator._core.FEngine()¶

Perform a series of overlapped Fourier transforms on real-valued data using OpenMP and windows.

Input arguments are:

signals: 2-D numpy (stands by samples) array of data to FFT
frequency: 1-D numpy.double array of frequency values in Hz for the
FFT channels
delays: 1-D numpy.double array of delays to apply to each stand

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
sample_rate: sample rate of the data (default=196e6)
window: Callable Python function for generating the window or None for no
window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLeve to zero disables time-domain blanking

Outputs:

fsignals: 3-D numpy.complex64 (stands by channels by FFT_set) of FFTd
data
valid: 2-D numpy.uint8 (stands by FFT_set) of whether or not the FFT
set is valid (1) or not (0)

lsl.correlator._core.PFBEngine()¶

Perform a series of overlapped polyphase filter bank transforms (4-tap plus a Hanning window) on real-valued data using OpenMP and windows.

Input arguments are:

signals: 2-D numpy (stands by samples) array of data to FFT
frequency: 1-D numpy.double array of frequency values in Hz for the
FFT channels
delays: 1-D numpy.double array of delays to apply to each stand

Input keywords are:

LFFT: number of FFT channels to make (default=64)
overlap: number of overlapped FFTs to use (default=1)
sample_rate: sample rate of the data (default=196e6)
window: Callable Python function for generating the window or None for no
window
clip_level: count value of ‘bad’ data. FFT windows with instantaneous
powers greater than or equal to this value greater are zeroed. Setting the ClipLeve to zero disables time-domain blanking

Outputs:

fsignals: 3-D numpy.complex64 (stands by channels by FFT_set) of FFTd
data
valid: 2-D numpy.uint8 (stands by FFT_set) of whether or not the FFT
set is valid (1) or not (0)

lsl.correlator._core.XEngine2()¶

Perform all XMACs for a data stream out of the F engine using OpenMP.

Changed in version 0.5: The second signal is not longer input as a conjugated array. Rather the conjucation is performed as part of the cross-correlation.

Input arguments are:

fsignals1: 3-D numpy.complex64 (stand by channels by FFT_set) array of FFTd
data from an F engine.
fsignals2: 3-D numpy.complex64 (stand by channels by FFT_set) array of
FFTd data from an F engine.
sigValid1: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the first signal.
sigValid2: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the second signal.

Ouputs:

visibility: 2-D numpy.complex64 (baseline by channel) array of cross-
correlated and averaged visibility data.

lsl.correlator._core.XEngine3()¶

Perform all XMACs for a data stream out of the F engine using OpenMP that creates the four linear polarization products

New in version 1.1.2.

Input arguments are:

fsignals1: 3-D numpy.complex64 (stand by channels by FFT_set) array of FFTd
data from an F engine.
fsignals2: 3-D numpy.complex64 (stand by channels by FFT_set) array of FFTd
data from an F engine.
sigValid1: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the first signal.
sigValid2: 1-D numpy.uint8 (FFT_set) array of whether or not the FFT_set is
valid (1) or not (0) for the second signal.

Ouputs:

visibility: 3-D numpy.complex64 (Stokes parameter (XX,XY,YX,YY) by baseline by
channel) array of cross-correlated and averaged visibility data.

DP-Style Signal Processing¶

This module contains a collection of function to speed up FIR filtering of TBW data (represented as numpy.int16 arrays) and the SoftwareDP class. The funtions provided in this module are:

integer16: Apply a FIR filter to numpy.int16 data,

integer16Delayed: Apply a FIFO delay and a FIR filter to numpy.int16 data, and

integerBeamformer: Software implementation of the DP beamformer.

lsl.common._fir.integer16()¶

Given a 1-D numpy.int16 array of data values and a numpy.int16 array of FIR coefficients, apply the coefficients to the data.

Inputs arguments are:

data: 1-D numpy.int16 array of data
coeffs: 1-D numpy.int16 array of FIR coefficients

Outputs:

result: 1-D numpy.float32 array of the filtered data

lsl.common._fir.integer16Delayed()¶

Given a 1-D numpy.int16 array of data values, a numpy.int16 array of FIR coefficients, and a FIFO sample delay, delay the signal and apply the coefficients to the data.

Inputs arguments are:

data: 1-D numpy.int16 array of data
coeffs: 1-D numpy.int16 array of FIR coefficients
sampleDelay: interger number of samples to delay the signal (must be >=0)

Outputs:

result: 1-D numpy.float32 array of the delayed and filtered data

lsl.common._fir.integerBeamformer()¶

Given a 2-D numpy.int16 array (stands by samples) of data values, 3-D array of FIR filter coefficients (stands by filters by taps), a 1-D numpy.int16 array of course (FIFO) delays, a 1-D numpy.int16 array of fine delay FIR filters, and a 2-D array of gains (stands by [XX, XY, YX, YY]), apply the delays and sum the signals.

Inputs arguments are:

data: 2-D numpy.int16 array of data (stands by samples)
coeffs: 3-D numpy.int16 array of FIR coefficients (stands by filters by taps)
course: 1-D numpy.int16 array of FIFO delays in samples
fine: 1-D numpy.int16 array of which FIR filter to apply for fine delay
gain: 2-D numpy.int16 arry of gains (stands by [XX, XY, YX, YY]), where XX is the X
contribution to the output X pol., XY is the X contribution to the output Y pol., YX is the Y contribtion to the output X pol., and YY is the Y contribu- tion to the output Y pol.

Outputs:

results: two element tuple (output X, outpuY) of the beamformer sum. Each element is
a 1-D numpy.float32 array.

Note

The structure of data is assumed to be that the polarizations are ordered, e.g., the X polarization of stand 1 is immediately followed by the Y polarization.