© ESO, 2016

1. Introduction

The exchange of data from optical and infrared interferometers between researchers has been greatly simplified by adopting a common format defined by Pauls et al. (2005) and now known as OIFITS version 1.

Since then, new interferometric instruments have introduced new capabilities such as sensitivity to polarisation, and new imaging techniques for multi-channel data have been developed that require the source spectrum – both of which were not contemplated in the first version of this format. Furthermore, as modern data archives such as the ESO Science Archive (Dolensky et al. 2008) require the presence of keywords in the FITS headers to enable searches based on, for example, target and instrument, such keywords need to be defined specifically for Optical Interferometry (OI).

Therefore, a revision of the standard became desirable (Young et al. 2008) and improvements have been discussed for two years on the JMMC forum at www.jmmc.fr/twiki/bin/view/Jmmc/OIFITSTwoProject.

The proposed enhancements have been endorsed by the former IAU Commission 54 and are described in the following text, including the formal definition of all extension tables, revised or not, for completeness. The reference for the new format shall consist of the original paper by Pauls et al. (2005) and this work.

In the following, the use of words like “must” and “should” follow the best current practice outlined in Bradner (1997).

2. Purpose and scope

By defining and maintaining a common data format, we hope to encourage the development of common software for the analysis of data from optical interferometers, and to facilitate the exchange of data between different research groups.

The format was initially intended to only support the storage of calibrated, time-averaged data, and this is still its purpose today. Fully supporting other uses, such as describing raw data, observational history, data reduction recipes, etc. will require the development of a specific Data Model in the framework of the Virtual Observatory (VO¹), which is beyond the scope of this paper.

However, even since version 1, the information stored in the OIFITS format was not entirely devoid of information about the instrument and interferometric array used. Practice, in particular for the AMBER instrument of VLTI (Petrov et al. 2007), has shown that OIFITS is adequate for storing semi-calibrated observations. Those are time series of instantaneous interferometric observables where instrumental bias has been removed and where error bars account for instrumental noise, known as level one (L1) data in the VO jargon.

Although the format presented here defines new keywords and tables that allow a more detailed description of the measured data, they are intended only for storing fully calibrated data: time averaged data, with all atmospheric and instrumental biases removed, known as L2 data in the VO jargon. Astronomers should use only fully calibrated OIFITS data to make inferences about the intrinsic brightness distribution of the observed target.

Interferometers are generally polarizing devices, but useful polarized optical interferometric observables have not been defined yet. However, we felt compelled to introduce some support for polarisation information. Without loss of generality, considering a number (hereafter NPOL) of distinct polarisation states for the observations leads to measurement of NPOL times all the interferometric observables. For example, if a Wollaston prism is used to make measurements on two orthogonal polarisation axes, we have NPOL=2.

In this document, we aim to keep the revised OIFITS tables compatible with their version 1. The only supplementary requirement for polarisation handling is that a distinct INSNAME must be assigned to each of the NPOL polarisations. A new optional OI_INSPOL table is introduced. This table serves two purposes:

• It stores the polarisation transfer function of each beam for eachINSNAME in the general form of Jones matrices (seeSect. 7.3).

• It serves as a hub for defining a relationship between all the polarized INSNAMEs. The intention is that, if this table is present, the data referenced by OI_INSPOL (via INSNAME) shall be kept together during merging, copying or splitting of OIFITS files (unless the intention is to select a subset of the polarisations).

OIFITS version 2 provides an optional table to store the correlations between interferometric observables, whether in wavelength, baseline, or time. By analogy with the INSNAME keyword, we introduce a CORRNAME keyword that uniquely references a table, OI_CORR, containing the sparse matrix representation of the correlations between selected observables of the dataset.

Finally, a drawback of OIFITS version 1 is also tackled here, namely the fact that the OI_VIS table could contain several kinds of data, which were not distinguished in the earlier format: correlated flux, differential (chromatic) visibilities and phases, or simply linear visibilities.

A reference implementation of this version of OIFITS has been developed by one of us (J. Young) in C ², We anticipate that implementations in other languages (IDL, Python, Java...) will be available in the near future.

3. Definitions and assumptions

In this section we only present definitions related to new quantities stored by the format, and refer the reader to Pauls et al. (2005) for all other definitions and assumptions. In this text the word “error” refers to the square root of a (temporal, spatial, theoretical...) variance.

3.1. Differential chromatic visibility

Differential chromatic visibility (in Table 7) is defined here as the ratio of visibility amplitudes (1)where | V_ref(u,v,λ) | is referred to as the reference visibility which is computed as a function of one or more reference channels. Thus, we consider here normalisation only to a reference derived from the data values themselves, rather than from model predictions. Such normalisation can be useful in cases where absolute calibration cannot be achieved, but where spectral features relative to a continuum level are not affected. One therefore needs to know, for each wavelength channel, which other channel had been used as reference. In case multiple channels have been used as the reference, the order of a wave-number polynomial function used to interpolate the reference visibility for the channel to be normalized shall be specified. The default order is zero, equivalent to a simple average (2)

3.2. Differential chromatic phase

Differential chromatic phase (Millour et al. 2006, see Table 7), is a phase difference between two wavelengths. An additional calibration step often applied to differential chromatic phase is to remove a wave-number slope or a higher-order polynomial from the observed phase φ(u,v,λ) = argV(u,v,λ): (3)where φ_ref(u,v,λ) = argV_ref(u,v,λ) is the phase at some adequately chosen reference channel that can, as in Eq. (1), be an average over multiple physical wavelength channels.

3.3. Noise model for complex visibility

Complex visibilities are the result of a coherent average which has removed the systematic phase noise induced by the atmosphere, either enabled by a fringe tracker, or offline analysis of dispersed fringes. At the level of estimates of the complex visibility from raw frames of the interferograms, the real and imaginary parts are uncorrelated (such as frames from an ABCD beam combiner, see Benisty et al. 2009). The calibration of the averaged product causes the noise ellipse to be elongated, as amplitude and phase are subject to different sources of systematic error. For this reason, version 1 of the standard implemented an amplitude and phase representation of the (average calibrated) complex visibilities. Upcoming new instruments such as GRAVITY (Eisenhauer et al. 2011) will allow visibility phases to be tied to a phase reference (nearby star), providing a data reduction chain of complex visibilities without ever converting them to modulus of the amplitude and phase. For that reason, we propose a new revision of the OI_VIS table which includes, in addition to the existing columns, optional storage for the real and imaginary parts of complex visibilities and their errors.

4. OIFITS file structure

OIFITS files must comply with the FITS standard (Hanisch et al. 2001), where shall be found acronyms and symbols not defined in this document. OIFITS files use binary table extensions following the primary header-data unit. Data types for each column are defined by the value of the TFORMn keywords in each extension header. This version introduces the use of the data type J (32 bit integers).

In addition to the mandatory FITS binary extension keywords defined in Hanisch et al. (2001), the keywords described in Table 1 must be present in the table headers. We recommend the use of DATASUM and CHECKSUM in the main header and all table headers³, TUNITn values are mandatory for all columns except those representing unitless values (such as STA_INDEX). Any other keyword is expected to be ignored by OIFITS readers. The FITS format defines a null value for each supported data type. The OIFITS format uses these type-dependent null values to identify individual data as being unmeasured, invalid, etc. and this document refers to such values as NULL.

4.1. Primary header

While the primary header was minimal in OIFITS version 1, we have added in Table 2 three small sets of keywords. They add ancillary information on, for example, the provenance of the OIFITS file itself (ORIGIN, AUTHOR), of the data (TELESCOP, INSTRUME, REFERENC, PROG_ID), on the observational method used (INSMODE, PROCSOFT, OBSTECH).

It is customary now to add in a FITS primary header other keywords enabling quick searches for observations matching certain criteria in a database or archive of OIFITS files, such as the JMMC’s optical interferometry database⁴. For example, the information about minimum and maximum baseline lengths used in the OIFITS file may be important for selecting only data resolving a target or providing a good uv-coverage for imaging. As the majority of instruments now provide data for multiple wavelength channels, the wavelength range recorded is a useful search parameter, as is the spectral resolution. Finally, the maximum elapsed time for a data point can be important information when searching for data on a wide binary where fringe smearing is a concern. These values are easily computable on-the-fly from the tables contained in the OIFITS file, since the amount of (reduced) data in an OIFITS file is still small.

For OIFITS writers needing to add such ancillary information in the main header, we suggest using the additional keywords listed in Table 2. These keywords are intended primarily for “atomic” OIFITS (one target, one instrument and instrument mode, one observing date, etc.) where there is no need to describe multiple (keyword value MULTI) observations. It is out of the scope of this document to further normalize the main header keywords for cases where the OIFITS file is a container of heterogenous data, those properties being more related to the problems of database management than to a physical description of interferometric observables. Nevertheless, see http://www.eso.org/sci/observing/phase3/p3sdpstd.pdf for a candidate standardisation of such ancillary keywords.

4.2. Table content

A valid OI exchange-format FITS file must contain one (and only one) OI_TARGET table, one or more OI_ARRAY tables, one or more OI_WAVELENGTH tables, plus any number of the data tables: OI_VIS, OI_VIS2, or OI_T3. Each data table must refer to an OI_WAVELENGTH and OI_ARRAY table that are present in the file. The requirement for the presence of an OI_ARRAY table was not part of version 1 of the format. All other new tables are optional. The revision number of the revised tables is equal to two, while it is equal to one for the new tables. Any future changes will require increments in the revision numbers of the altered tables.

If multiple tables of the same EXTNAME are present, each of them must have a unique value of the EXTVER keyword, as mandated by the FITS standard.

The tables can appear in any order. Other header-data units may appear in the file, provided their EXTNAMEs do not begin with “OI_”. Each instance of a table defined here must contain all the listed columns and header keywords, in no particular order.

Any of the tables may have extra keywords or columns beyond those defined in the standard. It would facilitate the addition of new keywords and columns in future releases of the standard if the non-standard keywords and column names were given a particular prefix, such as “NS_”, to avoid conflicts.

5. Target and instrument information tables

5.1. OI_TARGET (revision 2)

Keywords for the OI_TARGET table are listed in Table 3. The only differences from revision 1 are the optional additional column giving the category assigned to a target for the purpose of calibrating the data, and the recommendation to use EQUINOX 2000 for coordinates.

It is standard practice to interleave observations of science targets (SCI category) with observations of targets of known angular size (CAL category), to allow to calibrate the interferometric observables for the science objects. The optional column CATEGORY has been introduced for convenience as a reminder of the initial intent for observing each target. Its presence does not imply any particular data reduction level for the data stored in the other tables.

5.2. OI_ARRAY (revision 2)

Keywords for the OI_ARRAY table are listed in Table 4. As defined, the OI_ARRAY tables are mostly aimed at ground-based interferometry with separated telescopes but could be used for other cases depending on the value of the FRAME keyword. Each OI_ARRAY table in a file must have a unique value for ARRNAME. The stations involved in any of the interferometric observables stored in the other tables of a single OIFITS are identified via the STA_INDEX column. To be valid, an OIFITS file shall be written so that every combination of ARRNAME and STA_INDEX must refer to a unique OI_ARRAY entry that is present in the file.

Several interferometric observables stored in the OIFITS format are expressed as a ratio of a correlated flux to an incoherent flux. The area on the sky contributing to the latter is the photometric field of view (PFOV), and would typically be the PSF of a telescope in the array, the acceptance cone of an optical fiber, the diffraction pattern of a pinhole spatial filter... Therefore, we have added two columns to the OI_ARRAY table, FOV, which gives the radius of PFOV and FOVTYPE, which specifies whether the PFOV radial profile is Gaussian or rectangular.

The interferometric field of view (IFOV), over which photons received contribute to the correlated flux, is smaller than the PFOV, especially for co-axial Michelson beam combiners. In this case, the IFOV can be computed for each (u,v) data point with the information from the OI_WAVELENGTH table, since in this case , where λ is the wavelength, Δ_λ the spectral width and B the projected baseline length. The IFOV is also limited by the integration time, which, if too long, will cause fringe smearing for image pixels far away from the phase center.

Coordinate frame

If the FRAME keyword has the value GEOCENTRIC, then the coordinates are given in an earth-centered, earth-fixed, Cartesian reference frame. The origin of the coordinates is the earth’s center of mass. The z axis is parallel to the direction of the conventional origin for polar motion. The x axis is parallel to the direction of the intersection of the Greenwich meridian with the mean astronomical equator. The y axis completes the right-handed, orthogonal coordinate system.

We add an alternative value for FRAME, namely SKY, for data from sparse aperture masks, where the x axis points East, the y axis North and the z axis completes the right-handed coordinate frame (the aperture mask rotates with the sky). In this case, the ARRAYX, ARRAYY, and ARRAYZ coordinates must be zero.

5.3. OI_WAVELENGTH (revision 2)

Keywords for the OI_WAVELENGTH table are listed in Table 5. This table was introduced in the first version of the format to store the effective wavelength and bandwidth for each spectral channel of an instrument (identified by the INSNAME keyword). The number of spectral channels in the instrument is the number of rows in this table, that is, the NAXIS2 value, referred to as NWAVE in this document.

In this revision, we introduce the possibility of storing purely monochromatic values (EFF_BAND=0) in OI_WAVELENGTH, since such a table can be referenced, via the INSNAME keyword, by a new table, OI_FLUX, which may contain monochromatic spectra (see Sect. 7.1).

Name of detector

Each OI_WAVELENGTH table in a file must have a unique value for INSNAME. Particular attention to this point is recommended when aggregating OIFITS files which may have similar INSNAME values but different channel wavebands.

Wavelengths

Each OI_WAVELENGTH table describes either the spectral response of detector(s) with a number of spectral channels (traditional use defined in version 1 of the format), or the wavelengths of a monochromatic spectrum. In the latter case, EFF_WAVE contains the spectrum’s wavelengths and the EFF_BAND values are all zeros. In the former case, each table gives the observation wavelengths for one or more of the data tables (OI_VIS, OI_VIS2, OI_T3), and will often correspond to a single physical detector.

The EFF_WAVE column shall contain the best available estimate of the effective wavelength of each spectral channel, and the EFF_BAND column shall contain the best available estimate of the effective half-power bandwidth. These estimates should include the effect of the earth’s atmosphere, but not the spectrum of the target. (The effect of the target spectrum should be taken into account as part of any model-fitting or mapping process, in other words, the target spectrum is part of the model.)

6. Data tables

The tables containing observed data are the OI_VIS2, OI_VIS, OI_T3 and OI_FLUX tables.

6.1. Properties shared by all data tables

Start date of observations

This shall be a UTC date in the format YYYY-MM-DD, for example “1997-07-28”. In OIFITS version 2 only MJD and DATE-OBS must be used to express time. The TIME column is retained only for backwards compatibility and must contain zeros. The value in the MJD column shall be the mean UTC time of the measurement expressed as a modified Julian Day.

Integration time

The exchange format will normally be used for interchange of time-averaged data. The “integration time” INT_TIME is therefore the length of time over which the data were averaged to yield the given data point. In order that this information is useful when computing the effect of fringe smearing in the case of imaging distant companions or large structures, INT_TIME shall correspond to the time elapsed between the first and last recorded interferograms (frames) averaged to obtain a given data point.

Cross-referencing

Cross-referencing between FITS tables is not a generic feature of the FITS format, but is necessary for correct description of the interferometric data. When writing OIFITS tables, particular care must be taken to maintain the cross-references. Specifically, each data table must refer:

• to a particular OI_WAVELENGTH table describing thewavelength channels for the measurements, via the INSNAMEkeyword; and

• to an OI_ARRAY table, via the ARRNAME keyword; and

• optionally, to the OI_INSPOL table containing the same INSNAME; and

• optionally, to an OI_CORR table via the CORRNAME keyword.

There is a second level of cross-referencing possible, between table elements. Indeed, interferometric observables stored in an OIFITS file are physically associated: a phase closure in T3PHI, for example, can be the argument of the closure of three complex values whose squared norms are stored in three rows of the VIS2DATA column. Usually, the MJD column contains the same timestamp for all the simultaneous – therefore, related – observables, and suffices to link them. It should be stressed however that, according to the definition of MJD above, timestamps for two related observables can differ: values in an OIFITS being averaged and calibrated, the number of raw data used in the average, or the calibration process, may change the mean UTC time of the measurement even between related observables.

Data producers that want to add a more direct link than MJD between related quantities in different tables can add a non-standard column in the relevant tables, such as a NS_DATAINDEX column of TFORMn value “J”, containing integer hash numbers.

Flag

If a value in this vector is true, the corresponding datum must be ignored in all analysis.

6.2. OI_VIS2 (revision 2)

Keywords for the OI_VIS2 table are listed in Table 6.

Data arrays

NWAVE is the number of spectral channels, given by the NAXIS2 keyword of the relevant OI_WAVELENGTH table.

UV coordinates

UCOORD, VCOORD give the (u,v) coordinates in meters of the point in the UV plane associated with the vector of visibilities. The data points may be averages over some region of the UV plane, but the current version of the standard says nothing about the averaging process.

6.3. OI_VIS (revision 2)

Keywords for the OI_VIS table are listed in Table 7. This table has been used in the past to store the amplitude and phase of visibilities obtained through phase-preserving coherent integration. This revision intends to enable storage of complex coherent fluxes, visibilities and differential chromatic visibilities, uniquely identified so they can be modeled without ambiguity.

New keywords and columns

There are four new keywords in the header, AMPTYP, PHITYP, AMPORDER, and PHIORDER.

AMPTYP defines the type of data stored in VISAMP: absolute, differential or correlated flux. In the last case the usual TUNITn FITS keyword must be used to specify the flux unit (such as photon, count, Jy, adu, see footnote 5).

PHITYP is one of absolute or differential. The default for AMPTYP and PHITYP, if not present, is absolute.

If AMPTYP or PHITYP is differential, the newly-defined data column VISREFMAP must be present since this column contains the channel number(s) whose combination defines the reference channel used in computing the VISAMP and VISPHI values. The ith row of the 2-D matrix VISREFMAP specifies the reference channels for channel i. (In FITS the first dimension corresponds to the most rapidly varying index, also known as column-major ordering. This internal ordering is usually hidden by the low-level FITS libraries such as cfitsio.)

The combination of the channels in VISREFMAP defaults to a simple average, unless a polynomial fit of some order is defined through AMPORDER or PHIORDER.

If both VISAMP and VISPHI are differential, VISREFMAP shall apply to both. VISREFMAP must be present if either VISTYP or PHITYP is differential. If VISREFMAP is absent, neither can be differential.

OI_VIS revision 2 implements new optional columns RVIS and IVIS allowing the storage of complex visibilities or complex fluxes in (Real, Imaginary) representation rather than amplitude and phase. RVIS, IVIS and their associated errors RVISERR and IVISERR may be omitted. Their unit is given by the standard table header TUNITn keywords. Covariances between elements of the RVIS and IVIS vectors can be stored using the general OI_CORR sparse correlation matrix mechanism via the CORRINDX_RVIS and CORRINDX_IVIS columns.

Data arrays

As in revision 1, FLAG applies to VISAMP, VISAMPERR, VISPHI and VISPHIERR. VISAMP and VISPHI, as well as their associated errors VISAMPERR and VISPHIERR, can be NULL in the cases where the flag mechanism is not applicable, for example, if the instrument computes only VISPHI, or if flagging some incorrect VISAMP values would flag otherwise good VISPHI values. Similarly, if some values of RVIS or IVIS or RVISERR or IVISERR are meaningless, NULL values are to be used instead.

NWAVE is the number of spectral channels, given by the NAXIS2 keyword of the relevant OI_WAVELENGTH table.

UV coordinates

UCOORD, VCOORD give the (u,v) coordinates in meters of the point in the UV plane associated with the vector of visibilities – see Sect. 3 for details. The data points may be averages over some region of the UV plane, but the current version of the standard says nothing about the averaging process.

6.4. OI_T3 (revision 2)

Keywords for the OI_T3 table are listed in Table 8.

Data arrays

FLAG marks both the corresponding bispectrum amplitude (T3AMP) and phase (T3PHI) as invalid. To mark only the amplitude or phase as invalid, the relevant data values must be replaced by NULL (with FLAG remaining as false). If the dataset does not provide triple product amplitudes at all, T3AMP and T3AMPERR must contain only NULL values.

NWAVE is the number of spectral channels, given by the NAXIS2 keyword of the relevant OI_WAVELENGTH table.

Triple product UV coordinates

The U1COORD, V1COORD, U2COORD, and V2COORD columns contain the (u,v) coordinates of the bispectrum point in meters. U3COORD and V3COORD are not given since u₁ + u₂ + u₃ = 0, v₁ + v₂ + v₃ = 0. The corresponding data points may be averages in (bi-) spatial frequency space, but this version of the standard does not attempt to describe the averaging process.

7. Optional tables

7.1. OI_FLUX (revision 1)

OIFITS version 2 introduces this optional table intended as a container for raw or calibrated flux measurements. Corresponding wavelengths are referenced with the INSNAME keyword. The content of the table depends on the single-character keyword header CALSTAT. Keywords for the OI_FLUX table are listed in Table 9. FLUXDATA and FLUXERR are in units of their corresponding TUNIT, which must be present⁵.

If CALSTAT is C (Calibrated), the fluxes listed are flux-calibrated spectra obtained with the interferometric instrument itself, if it provides such a measurement, or with another instrument. In both cases this spectrum is useful for modeling sources with physical emission components where it provides the constraint of the total flux. The spectrum is the spectrum of the object and does not depend on the telescope used: the table shall not contain ARRNAME and STA_INDEX.

If CALSTAT is U (Uncalibrated), ARRNAME and the STA_INDEX column must be present, and the flux stored in FLUXDATA is the flux measured on the telescope of array ARRNAME indicated by STA_INDEX. In this case, the table shall not contain FOV and FOVTYPE. (The field of view is given in the OI_WAVELENGTH table referenced by INSNAME.)

Data arrays

NWAVE is the number of distinct channels, given by the NAXIS2 keyword of the relevant OI_WAVELENGTH table.

7.2. OI_CORR (revision 1)

There is a need to describe correlations between any kinds of OIFITS observables, over a limited timespan (hours at most) determined by the calibration procedures. For an example where such correlations are derived, see Perrin (2003).

The following addition to the standard allows the definition of a set of correlated real-valued data { x_i } that may span multiple OIFITS tables, of any type. Data may be correlated in wavelength, baseline, or time. Correlations between different kinds of observable can also be described. An OIFITS file may contain multiple such sets, to accommodate merging of multiple data sets. The correlations are described by a sparse dimensionless correlation matrix (4)which is stored in a new OI_CORR table (Table 10). The covariance matrix can straightforwardly be obtained from the correlation matrix using the standard deviations from the data tables, such as VIS2ERR in OI_VIS2 which is the standard deviation of the squared visibility.

Because the number of potentially correlated data is relatively large – of order 10⁴; a six-element interferometer measuring squared visibilities, triple amplitudes and closure phases in 100 spectral channels for two hours with an observing cadence of 20 min would generate 27 000 data – and at the same time many of these correlations are not significant, we have adopted a sparse representation of the correlation matrix. The important elements of the matrix are stored as triplets { i,j,C_ij } and the remaining elements shall be assumed to be zero. Since C_ij = C_ji and C_ii = 1, we adopt the convention of only storing elements with j>i. The indices i and j are stored as signed 32-bit integers (J type code in TFORMn). (The indices are all positive but unsigned integers can only be represented in FITS by specifying an offset using the BZERO keyword.)

Each of the data tables in a correlated data set shall have a keyword CORRNAME that is used to look up the corresponding OI_CORR table. The correspondence between the position of a value in a data table and its index into the correlation matrix is given by the following new columns: CORRINDX_VISAMP, CORRINDX_VISPHI, CORRINDX_RVIS and CORRINDX_IVIS in OI_VIS, CORRINDX_VIS2DATA in OI_VIS2, CORRINDX_T3AMP and CORRINDX_T3PHI in OI_T3 and CORRINDX_FLUXDATA in OI_FLUX . These columns are all of data type J(1). If all of the data in a table are uncorrelated, the CORRNAME keyword and all of the CORRINDX_* columns shall be omitted. If some of the table data are correlated, correlation matrix indices shall be specified for all of the data in the table, but the zero-valued correlations shall be omitted from the OI_CORR table.

The single CORRINDX_VIS2DATA value in a particular row in OI_VIS2 gives the index into the correlation matrix for the first element of the VIS2DATA vector, which contains NWAVE values for the defined spectral channels. The index for the jth value of the data vector is given by (CORRINDX˙VIS2DATA+ j−1). In other words, an element in the correlation matrix with indices (i,j) gives the value of the correlation between the VIS2DATA measurement in the row of the referencing OI_VIS2 with the largest CORRINDX_VIS2DATA value i_r less than or equal to i and channel index (i−i_r + 1) and the measurement in OI_VIS2 obtained in the same way using index j instead of i. Therefore, the indices implied by the CORRINDX values shall be unique within the correlated data set. The other CORRINDX columns give the correlation matrix index for the first element of the similarly-named, real-valued data column. An example of use is described in Appendix A.

7.3. OI_INSPOL (revision 1)

In general, each input beam contributing to the correlated flux on a baseline is polarized to some extent, either by design or by the unavoidable effects of partially-polarizing elements in the optical train of the interferometer. Although polaro-interferometric observations in the optical and infrared range are possible, there is no good example yet of true polaro-interferometric observations which provided a measurement of the source’s Stokes parameters. It is thus out of the scope of this document to standardize polaro-interferometric calibrated data. However, we feel compelled to provide a way to note in the OIFITS format that the measurements were subject to instrumental polarisation, and, in the case of simultaneous or related measurements in various states of polarisation, provide an internal link between the classical observables of OIFITS and the instrumental polarisation state in which they were obtained. This new table is purely instrumental and named OI_INSPOL.

In order to ensure backwards compatibility with current OIFITS readers, we identify each functional polarisation state by a different INSNAME. For example, data taken through a Wollaston prism (two orthogonal linear polarisations) provides two statistically independent series of interferograms. Each serie will produce OI observables, perfectly valid independently of the other. It is just a matter of bookkeeping to note that one serie was taken with horizontal polarisation through the Wollaston and the other through the vertical polarisation. The new OI_INSPOL table is the central hub that links all the INSNAMEs (all the polarized measurements). Keywords for the OI_INSPOL table are listed in Table 11.

The OI_INSPOL table uses the Jones matrix representation as a beam-based description of how the optical system operates on the source’s light. This formalism does not permit the description of the depolarizing effects that could occur between the telescope(s) and the recording of the interferogram. However, being an operator on the electrical field of the light, it allows description of the effects on the complex coherence betwen two beams.

The OI_INSPOL table stores a Jones matrix for each wavelength, time interval, and polarisation state as cross-referenced via the INSNAME column. The four complex elements of the Jones matrix are stored in the columns JXX, JYY, JXY and JYX. These values are beam-based, and can be in principle measured or modeled as a function of time. In the simplest case, a polarizer in front of the camera would record only one polarisation, or a Wollaston in the same place would permit recording of two orthogonally polarized interferograms. Then OI_INSPOL would serve only to describe the ORIENTation of the polarisation state of the INSNAME (or INSNAMEs) interferometric data. More complicated cases, in particular a time-varying instrumental polarisation due to rotation of a polarizing element, are possible. The MJD_OBS and MJD_END values can describe any variation of the complex Jones matrices independently of the time-tagging of data contained the other tables. Table 12 shows a few examples of Jones matrices for simple polarizers. The sign of the imaginary parts must be given in the theoretical framework where the wave function used in propagation equations of light reads exp(kz−iωt) (Lawson 2000, p. 10).

OI_INSPOL is an optional table: if OI_INSPOL is present, it must encompass at least all the time entries and baselines present in all the other tables referenced by all the values stored in its INSNAME column. OI_INSPOL is also experimental: OIFITS readers or writers should make provision for the possible augmentation of this table in future releases.

7.4. Guidelines for other tables

It may be useful to incorporate other tables in an OIFITS file. For example, there might be one that contains instrument specific information, such as the backend configuration. Another optional table could contain information relevant to astrometry. The only requirement imposed by the format is that EXTNAMEs of additional tables must not begin with “OI_”.

8. Summary

Drawing on experience from a dozen years of community use, we have revised the OIFITS data format to:

• Address the needs of the new interferometric instruments thatwill routinely produce images, adding ancillary data and tablesuseful for image reconstruction purposes.

• Provide a rigorous description of the interferometric observables and how they are computed, especially in the case of differential observables.

• Provide a rigorous description of measurement errors and their correlation.

• Tentatively take into account simple polarisation properties of the instrument.

• Pave the way to a more formal description of the optical interferometry Data Model, as developed for radio interferometry for example.

• Add bookkeeping keywords necessary to feed the emerging databases of optical interferometry measurements.

This has been done while guaranteeing backward compatibility with version 1, ensuring continuous use of older software without changes. There are already a few libraries available for reading and writing this format, and we expect that it will soon be used by the end data products of the PIONIER, GRAVITY and MATISSE instruments, and receive wide support from the optical interferometry community.

Acknowledgments

Initial development of the format was done under the auspices of the IAU Working Group on Optical and infrared Interferometry. Version 2 has been pursued by the (discontinued) IAU Commission 54 and JMMC, with the active participation of many community interferometrists, in particular: Fabien Baron, Philippe Bério, Laurent Bourgès, Leonard Burtscher, Alain Chelli, Pierre Cruzalèbes, Mike Ireland, Brian Kloppenborg, Sylvestre Lacour, Vincent Lapeyrere, Jean-Baptiste le Bouquin, Guillaume Mella, Florentin Millour, John Monnier, Jörg-Uwe Pott, Antony Schutz, Michel Tallon, Theo ten Brummelaar, Eric Thiébaut. We thank I. Percheron, A. Dobrzycki and our anonymous referee for many useful comments.

This work has benefitted of the support of the European Community’s Seventh Framework Programme (FP7/2013–2016) under Grant Agreement 312430 (OPTICON) and of the French ANR POLCA, ANR-10-BLAN-0511.

References

Appendix A: On the use of correlation matrices in OIFITS

We describe here a concrete example of the use of OI_CORR. Consider a dataset comprising two OI_VIS2 tables and two OI_T3 tables, as shown in Table A.1. Each table contains observations made simultaneously on three baselines in four wavelength channels. Depending on how we want to express the correlations between some of the observables within these tables, we will use different OI_CORR tables (with unique CORRNAMEs).

If we need to express the spectral correlations of the T3AMP measurements only, we would write a 4 × 4 full correlation matrix for each OI_T3 table. These two matrices can be written as two sparse matrices in two separate OI_CORR tables, “T1” and “T2” (one per OI_T3). The value of CORRINDX_T3AMP would be 1 for both OI_T3 tables as shown in Table A.1 in the lower diagonal cells.

If we need to express the time and baseline correlations between the VIS2DATA measurements only, we have 2 × 3 × 4 = 24 measurements in the two OI_VIS2 tables (12 per table), requiring a 24 × 24 correlation matrix. The correlations between these measurements would be expressed as a single OI_CORR table (“V”) with NDATA= 24. In this example, the CORRINDX_VIS2DATA values for each row in OI_VIS2 are also given in the lower diagonal cells of Table A.1.

As T3AMP measurements share baselines with VIS2DATA measurements, we could give the correlations between T3AMP and VIS2 measurements in a single OI_CORR table. In this case, non-zero correlations would be contained in a matrix of NDATA= 24 + 2 × 4 = 32 rows and columns, the indices CORRINDX_VIS2DATA and CORRINDX_T3AMP are now given in the upper diagonal cells of Table A.1 and all data tables would reference the same OI_CORR table (“V&T”).

All Tables