oifits: auxiliary module to read and write oifits files
PyHdust auxiliary module: third-part module for reading/writing OIFITS files.
This module is NOT related to the OIFITS Python module provided at http://www.mrao.cam.ac.uk/research/OAS/oi_data/oifits.html It is a (better) alternative. It official page is https://github.com/pboley/oifits/
To open an existing OIFITS file, use the oifits.open(filename) function, where ‘filename’ can be either a filename or HDUList object. This will return an oifits object with the following members (any of which can be empty dictionaries or numpy arrays):
array: a dictionary of interferometric arrays, as defined by the OI_ARRAY tables. The dictionary key is the name of the array (ARRNAME).
corr: a dictionary of correlation matrices, as defined by the OI_CORR table. The dictionary key is the name of the table (CORRNAME).
header: the header from the primary HDU of the file.
target: a numpy array of targets, as defined by the rows of the OI_TARGET table.
wavelength: a dictionary of wavelength tables (OI_WAVELENGTH). The dictionary key is the name of the instrument/settings (INSNAME).
vis, vis2, t3 and flux: numpy arrays of objects containing all the measurement information. Each list member corresponds to a row in an OI_VIS/OI_VIS2/OI_T3/OI_FLUX table.
inspol: a numpy array of objects containing the instrumental polarization information, as defined by the rows of the OI_INSPOL table.
A summary of the information in the oifits object can be obtained by using the info() method:
import oifits
oifitsobj = oifits.open('foo.fits')
oifitsobj.info()
As of version 0.4, revision 2 of the OIFITS standard (Duvert, Young & Hummel, 2017, A&A 597, A8) is supported, with the exception of correlations and polarization. If you need support for these features of the OIFITS2 standard, please open an issue on github. Support for writing OIFITS2 files is currently experimental.
Earlier versions of this module made an ad-hoc, backwards-compatible change to the OIFITS revision 1 standard originally described by Pauls et al., 2005, PASP, 117, 1255. The OI_VIS tables in OIFITS files read by this module can contain two additional columns for the correlated flux, CFLUX and CFLUXERR , which are arrays with a length corresponding to the number of wavelength elements (just as VISAMP). Support for writing these additional columns was removed in version 0.4, as the OIFITS standard now provides a mechanism for saving correlated flux measurements in OI_VIS tables.
The main purpose of this module is to allow easy access to your OIFITS data within Python, where you can then analyze it in any way you want. As of version 0.3, the module can now be used to create OIFITS files from scratch without serious pain. Be warned, creating an array table from scratch is probably like nailing jelly to a tree. In a future verison this may become easier. Note that array tables are a requirement only for OIFITS2.
The module also provides a simple mechanism for combining multiple oifits objects, achieved by using the ‘+’ operator on two oifits objects: result = a + b. The result can then be written to a file using result.save(filename).
Many of the parameters and their meanings are not specifically documented here. However, the nomenclature mirrors that of the OIFITS standard, so it is recommended to use this module with the OIFITS1/OIFITS2 references above in hand.
Beginning with version 0.3, the OI_VIS/OI_VIS2/OI_T3 classes now use masked arrays for convenience, where the mask is defined via the ‘flag’ member of these classes. This also concerns the OI_FLUX tables from OIFITS2. Beware of the following subtlety: as before, the array data are accessed via (for example) OI_VIS.visamp; however, OI_VIS.visamp is just a method which constructs (on the fly) a masked array from OI_VIS._visamp, which is where the data are actually stored. This is done transparently, and the data can be accessed and modified transparently via the “visamp” hidden attribute. The same goes for correlated fluxes, differential/closure phases, triple products, total flux measurements, etc. See the notes on the individual classes for a list of all the “hidden” attributes. Example of OIfits merge (same target):
import pyhdust.oifits as oifits
oidata1 = oifits.open('file1.fits')
oidata2 = oifits.open('file2.fits')
oifits.matchtargetbyname = True
merge = oidata1 + oidata2
oimerge.save('merged.fits')
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- co-author:
Daniel Moser
- license:
Copyright 2024 Paul Boley
- class pyhdust.oifits.OI_ARRAY(frame, arrxyz, stations=(), revision=1)[source]
Contains all the data for a single OI_ARRAY table. Note the hidden convenience attributes latitude, longitude, and altitude.
- class pyhdust.oifits.OI_FLUX(timeobs, int_time, fluxdata, fluxerr, flag, wavelength, target, calibrated, fluxunit, fluxerrunit, corr=None, array=None, station=None, fov=None, fovtype=None, revision=1)[source]
Class for storing raw or calibrated flux measurements. To access the data, use the following hidden attributes:
fluxdata, fluxerr
- class pyhdust.oifits.OI_STATION(tel_name=None, sta_name=None, diameter=None, staxyz=[None, None, None], fov=None, fovtype=None, revision=1)[source]
This class corresponds to a single row (i.e. single station/telescope) of an OI_ARRAY table.
- class pyhdust.oifits.OI_T3(timeobs, int_time, t3amp, t3amperr, t3phi, t3phierr, flag, u1coord, v1coord, u2coord, v2coord, wavelength, target, corr=None, corrindx_t3amp=None, corrindx_t3phi=None, array=None, station=(None, None, None), revision=1)[source]
Class for storing triple product and closure phase data. To access the data, use the following hidden attributes:
t3amp, t3amperr, t3phi, t3phierr
- class pyhdust.oifits.OI_VIS(timeobs, int_time, visamp, visamperr, visphi, visphierr, flag, ucoord, vcoord, wavelength, target, corr=None, array=None, station=(None, None), cflux=None, cfluxerr=None, revision=1, corrindx_visamp=None, corrindx_visphi=None, corrindx_rvis=None, corrindx_ivis=None, amptyp=None, phityp=None, amporder=None, phiorder=None, ampunit=None, rvisunit=None, ivisunit=None, visrefmap=None, rvis=None, rviserr=None, ivis=None, iviserr=None)[source]
Class for storing visibility amplitude and differential phase data. To access the data, use the following hidden attributes:
visamp, visamperr, visphi, visphierr, flag; and possibly cflux, cfluxerr.
- class pyhdust.oifits.OI_VIS2(timeobs, int_time, vis2data, vis2err, flag, ucoord, vcoord, wavelength, target, corr=None, corrindx_vis2data=None, array=None, station=(None, None), revision=1)[source]
Class for storing squared visibility amplitude data. To access the data, use the following hidden attributes:
vis2data, vis2err