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¶
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.2¶
Added a -v/–lwasv option to correlateTBN.py and tbnSpectra.py
Added better input file type checking to the various “correlate” and “spectra” scripts
Switched back to CDDIS for ionospheric data
Fixed an error when setting beam/dipole mode for STEPPED SDFs
Fixed a bug in updateLSLSSMIF.py when trying to revert a SSMIF
Added a color keyword to the classes in lsl.common.busy and lsl.common.progress
Added a new BusyIndicatorPlus class to lsl.common.busy
Added a new DownloadBar class to lsl.common.progress
Reduced the number of warning messages generated by STEPPED SDFs
Added automatic updates of leap second information
Changed the IDF and SDF modules to be more flexible on the styles of input coordinates
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
Updated the documentation in lsl.common.stations.Cable to make it more clear what attenuation and gain are
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).
-
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).
-
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:
,where
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.
-
static
-
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.
-
classmethod
-
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.
-
static
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.
-
class
lsl.transform.SkyPosition¶ Base abstract class for representing positions on the sky.
-
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.
-
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.
-
property
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)
See also
numpy.hanning, numpy.hamming, numpy.bartlett, numpy.blackman, numpy.convolve scipy.signal.lfilter
TODO: the window parameter could be the window itself if an array instead of a string
-
lsl.misc.mathutils.sphfit(az, alt, data, lmax=5, degrees=False, real_only=False)¶ Decompose a spherical or semi-spherical data set into spherical harmonics.
- Inputs:
- az: 2-D numpy array of azimuth coordinates in radians or degrees if the
degrees keyword is set
- alt: 2-D numpy array of altitude coordinates in radian or degrees if the
degrees keyword is set
- data: 2-D numpy array of the data to be fit. If the data array is purely
real, then the real_only keyword can be set which speeds up the decomposition
lmax: integer setting the maximum order harmonic to fit
- Keywords:
- degrees: boolean of whether or not the input azimuth and altitude coordinates
are in degrees or not
real_only: boolean of whether or not the input data is purely real or not. If the data are real, only coefficients for modes >=0 are computed.
Returned is a 1-D complex numpy array with the spherical harmonic coefficients packed packed in order of increasing harmonic order and increasing mode, i.e., (0,0), (1,-1), (1,0), (1,1), (2,-2), etc. If the real_only keyword has been set, the negative coefficients for the negative modes are excluded from the output array.
Note
sphfit was designed to fit the LWA dipole response pattern as a function of azimuth and elevation. Elevation angles are mapped to theta angles by adding pi/2 so that an elevation of 90 degrees corresponds to a theta of 180 degrees. To fit in terms of spherical coordianates, subtract pi/2 from the theta values before running.
-
lsl.misc.mathutils.sphval(terms, az, alt, degrees=False, real_only=False)¶ Evaluate a set of spherical harmonic coefficents at a specified set of azimuth and altitude coordinates.
- Inputs:
terms: 1-D complex numpy array, typically from sphfit
- az: 2-D numpy array of azimuth coordinates in radians or degrees if the
degrees keyword is set
- alt: 2-D numpy array of altitude coordinates in radian or degrees if the
degrees keyword is set
- Keywords:
- degrees: boolean of whether or not the input azimuth and altitude coordinates
are in degrees or not
- real_only: boolean of whether or not the input data is purely real or not. If
the data are real, only coefficients for modes >=0 are computed.
Returns a 2-D numpy array of the harmoics evalated and summed at the given coordinates.
Note
sphfit was designed to fit the LWA dipole response pattern as a function of azimuth and elevation. Elevation angles are mapped to theta angles by adding pi/2 so that an elevation of 90 degrees corresponds to a theta of 180 degrees. To spherical harmonics in terms of spherical coordianates, subtract pi/2 from the theta values before running.
-
lsl.misc.mathutils.to_dB(factor)¶ Convert from linear units to decibels.
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.
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, color=None)¶ 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.
-
class
lsl.common.busy.BusyIndicatorPlus(message='Busy', interval=0.1, width=10, style='flow', color=None)¶ -
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.DownloadBar(max=100, span=70, sym='=', print_percent=True, color=None)¶ Modified version of the ProgressBarPlus class that has a crude bandwidth estimator. At the end of the download the total file size (max) is displayed instead of the average rate.
- Example Usage:
>>> import sys >>> from progess import DownloadBar >>> db = DownloadBar() >>> db.inc() >>> sys.stdout.write(db.show()) >>> sys.stdout.flush()
Note
The timing feature is only active when the inc()/dec() functions are called.
New in version 2.0.2.
-
show()¶ Build a string representation of the download bar and return it.
-
class
lsl.common.progress.ProgressBar(max=100, span=70, sym='=', print_percent=True, color=None)¶ 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, color=None)¶ Extended version of the ProgressBar class that has a crude time estimator.
- Example Usage:
>>> import sys >>> from progess import ProgressBarPlus >>> pb = ProgressBarPlus() >>> 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.
-
property
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.Projectinstance 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.SDMinstance 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.LWAStationobject. Optionally, update thelsl.common.stations.Antennainstances 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.Antennainstances, 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.
-
property
-
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.
-
property
-
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.
-
property
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.
-
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.
-
property
-
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.
-
property
-
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.
-
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.
-
property
-
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.
-
property
-
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
-
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.
-
property
-
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.
-
property
-
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.
-
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.
-
property
-
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.
-
property
-
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.
-
property
-
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.
-
property
-
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.
-
property
-
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.
-
property
-
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.
-
property
-
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.
-
property
-
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.
-
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.
-
property
-
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.readermodule 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.FrameBufferBaseA sub-type of FrameBufferBase specifically for dealing with COR frames. See
lsl.reader.buffer.FrameBufferBasefor 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.FrameBufferBaseA sub-type of FrameBufferBase specifically for dealing with DRX frames. See
lsl.reader.buffer.FrameBufferBasefor 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
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:
objectFrame 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.FrameBufferBaseA sub-type of FrameBufferBase specifically for dealing with TBF frames. See
lsl.reader.buffer.FrameBufferBasefor 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.FrameBufferBaseA sub-type of FrameBufferBase specifically for dealing with TBN frames. See
lsl.reader.buffer.FrameBufferBasefor 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
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.FrameBufferBaseA sub-type of FrameBufferBase specifically for dealing with VDIF frames. See
lsl.reader.buffer.FrameBufferBasefor 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¶
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.dateobject.
-
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.LWAStationobject.
-
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¶
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.stationsmodule 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.stationsmodule 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.
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.
See also
lsl.sim.tbw
-
class
lsl.writer.vdif.Frame(stand=0, time=0, bits=8, data=None, sample_rate=196000000.0)¶ Object to create and write a VDIF (VLBI Data Interchange Format) frame (version 1, June 26, 2009).
-
create_raw_frame()¶ Using the data and information stored in the object, create a numpy array on unsigned 1-byte integers that represents the frame.
-
write_raw_frame(fh)¶ Create a numpy representation of the VDIF frame and then write it to the specified 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.stationmodule 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.stationmodule 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.calcSpectrafor details on using window functions.
-
lsl.correlator.filterbank.fft16(signal, N, window=<function null_window>)¶ Sub-type of
lsl.correlator.filterbank.fftthat uses 16 taps.
-
lsl.correlator.filterbank.fft2(signal, N, window=<function null_window>)¶ Sub-type of
lsl.correlator.filterbank.fftthat uses two taps.
-
lsl.correlator.filterbank.fft32(signal, N, window=<function null_window>)¶ Sub-type of
lsl.correlator.filterbank.fftthat uses 32 taps.
-
lsl.correlator.filterbank.fft4(signal, N, window=<function null_window>)¶ Sub-type of
lsl.correlator.filterbank.fftthat uses four taps.
-
lsl.correlator.filterbank.fft8(signal, N, window=<function null_window>)¶ Sub-type of
lsl.correlator.filterbank.fftthat 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.stationsmodule 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
Read in and work with FITS IDI and UVFITS files. Returns either a CorrelateDataIDI or CorrelatedDataUV instance.
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.AntennaArrayinstance that represents the array where the data was obtained. This is useful for simulation proposes and computing source positions.
- get_antennaarray - Return a
get_observer - Return a ephem.Observer instance representing the array
- get_data_set - Return a
lsl.imaging.data.VisibilityDataSetor lsl.imaging.data.VisibilityDataobject for all baselines for a given set of observations
- get_data_set - Return a
- 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.LWAStationinstance for the array
- station - LSL
date_obs - Datetime object for the reference date of the FIT IDI file
antennas - List of
lsl.common.stations.Antennainstances
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.
Return a
lsl.imaging.data.VisibilityDataSetorlsl.imaging.data.VisibilityDataobject 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 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.
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.AntennaArrayinstance that represents the array where the data was obtained. This is useful for simulation proposes and computing source positions.
- get_antennaarray - Return a
get_observer - Return a ephem.Observer instance representing the array
- get_data_set - Return a
lsl.imaging.data.VisibilityDataSetor lsl.imaging.data.VisibilityDataobject of all baselines for a given set of observations
- get_data_set - Return a
- 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.LWAStationinstance for the array
- station - LSL
date_obs - Datetime object for the reference date of the FIT IDI file
antennas - List of
lsl.common.stations.Antennainstances
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.
Return a
lsl.imaging.data.VisibilityDataSetorlsl.imaging.data.VisibilityDataobject 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.VisibilityDataSetobject, 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.
If the tile is empty, use the clipped mean for the background.
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.stationsmodule 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.stationsmodule 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.stationsmodule 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.Frametbn.SimFrame extends the
lsl.reader.tbn.Frameobject 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.Frameobject 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.Framedrx.SimFrame extends the
lsl.reader.drx.Frameobject 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.Frameobject 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
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.VisibilityDataSetobject 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.stationmodule 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.VisibilityDataSetobject 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.VisibilityDataSetobject. 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.VisibilityDataSetobject 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.bufferbuffer 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.fitsidiif 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.