`virgil.oifits`

Read and write OIFITS files with astropy.io.fits alone. This is the maintained OIFITS path; OIData uses read_oifits whenever it is given a file path or an opened HDUList (including pyoifits objects).

The reader supports:

several wavelength channels (every baseline × channel becomes one sample);
several OI_VIS2/OI_VIS/OI_T3 tables and epochs, matched by ARRNAME, INSNAME (or another INSNAME of the same array with identical wavelengths), station indices and MJD;
FLAG columns and non-finite values, which are left out of the observables;
several targets, chosen with target=;
absolute phases from OI_VIS VISPHI when there is no OI_T3.

Closure-phase triangles (a, b, c) find their baselines (a, b), (b, c) and (a, c) in the visibility table with the same ARRNAME and INSNAME, or else in one of the same array with identical wavelengths (the standard does not require T3 and V² tables to share an INSNAME; station numbers belong to an array, so another ARRNAME is never used). A baseline stored reversed is used as the conjugate. A baseline stored in neither orientation (some MIRC-X and ESO phase-3 files omit a baseline's V²) is placed at the OI_T3 row's own (u, v) as a flagged sample, with one warning per file giving the number of such legs.

Functions

Read and write OIFITS files using only astropy.io.fits.

read_oifits turns an OIFITS file (a path or any astropy HDUList) into the record that virgil.oidata.OIData is built from, and write_oifits writes an OIData or a dictionary of tables to an OIFITS2 file. Each (baseline, wavelength) sample is one element of the flat u, v and wavel arrays; closure phases index into them. See OIFITS files for the details.

`read_oifits(source, target=None, insname=None, frame_mjd='mean', extras=(), bandwidth=False)`

Read an OIFITS file into the record OIData(source) is built from.

Prefers OI_VIS2 over amplitudes and OI_T3 over absolute phases; see OIFITS files for the tables read and how closure phases are matched. Source: Pauls et al. (2005), references; Duvert et al. (2015), references.

Parameters:

Name	Type	Description	Default
`source`	`str, os.PathLike, astropy.io.fits.HDUList, or a list of them`	A path or an opened file. A list is read in order and concatenated.	required
`target`	`str or int`	Target to keep, by name or `TARGET_ID`; needed for several targets, and a name for several files.	`None`
`insname`	`str or sequence of str`	Keep only tables with this `INSNAME`; needed for several instruments (see one instrument at a time).	`None`
`frame_mjd`	`(mean, row)`	Give every sample of a frame the frame's mean `MJD` (default), or keep each row's own.	`"mean"`
`extras`	`sequence of str`	Any of `"flux"`, `"nflux"`, `"t3amp"`, `"visamp"`, `"visphi"` (see extras).	`()`
`bandwidth`	`bool`	Also return each sample's `EFF_BAND` as `"bandwidth"`.	`False`

Returns:

Type	Description
`dict`	Flat per-sample `u`, `v`, `wavel` (metres), `vis`/`d_vis` (V², or amplitudes if `v2_flag` is False; one-sigma errors; `vis_flag` True = bad), `phi`/`d_phi` (radians, with `phi_flag`), `i_cps1`/`i_cps2`/`i_cps3`, `cp_flag`, `v2_flag`, `mjd`, `frame`, and a dict per requested extra.

Raises:

Type	Description
`ValueError`	For several targets or instruments without `target`/`insname`, differential or correlated-flux data, or unusable `OI_T3` coordinates.

`write_oifits(data, filename, overwrite=True)`

Write an OIData or a dictionary of OIFITS tables to an OIFITS2 file.

An OIData is written as OI_VIS2 with OI_T3 or OI_VIS phases, and read back by read_oifits to the same observables, errors, flags, frames, wavelengths and (u, v), and the times if any (else MJD 0). Wavelengths are float32 (relative error 6e-8); frames at one MJD get distinct TIMEs so they stay apart; closure phases without station indices get placeholder stations (STAPLACE). A dictionary of tables (columns as in writing OIFITS, upper-case OIFITS names) has phases in degrees. Source: Duvert et al. (2015), references.

Parameters:

Name	Type	Description	Default
`data`	`OIData or dict`	V² with closure or absolute phases, or a mapping of table name to a dict of columns (`OI_WAVELENGTH` and a data table).	required
`filename`	`str or PathLike`	Output path. Missing parent directories are created.	required
`overwrite`	`bool`	Replace an existing file (default True).	`True`

Returns:

Type	Description
`Path`	The path written.

Raises:

Type	Description
`TypeError`	If `data` is neither an `OIData` nor a mapping.
`ValueError`	If `data` is the flat record `read_oifits` returns (write `OIData(record)` instead), or an `OIData` has a layout OIFITS cannot hold (the message says which): extras, gains, projected or uv-grid data, a station index above 32767. No file is written.
`KeyError`	If a dictionary lacks `OI_WAVELENGTH` or a data table.
`OSError`	If the file exists and `overwrite` is False.

`build_hdulist(tables)`

Build the OIFITS2 HDUList that :func:write_oifits writes.

Useful for adding non-standard columns or keywords before writing.