distroi.data.oi_data module

A module to handle OIFITS data.

Contains the master OIData class to store optical inteferometric (OI) observables, taken using the same instrument setup, and additional functions to take radiative transfer (RT) model images and convert them to interferometric observables at the spatial frequencies of the observables.

Notes:

With the aim of flexibility in including multiple files and computational ease, the OIData class doesn’t fully reflect all the infromation stored in the OIFITS file format. For example, the wavelengths and baselines/triplets at which observables were taken is stored in the relevant observable properties. E.g. the wavelengths and baselines associated to the OI_VIS2 measurements are stored as a np.ndarray inside the OIData.vis2 instance property itself, instead of in a separate property mirroring the OI_WAVELENGTH and OI_ARRAY tables inside the OIFITS files.

class distroi.data.oi_data.OIData

Bases: object

Describes a set of optical interferometry data.

Optical interferometry data container class, allowing to represent simultaneously the data contained in multiple OIFits files observed using the same array and instrument setup.

header

Primary header dictionary. Taken from the first file that’s read in.

Type:

dict

target

Object representing the OI_TARGET table of an OIFITS file. Taken from the first file that’s read in.

Type:

OITarget

vis

Object representing data in the OI_VIS tables concatenated over the considered OIFITS files.

Type:

OIVis

vis2

Object representing data in the OI_VIS2 tables concatenated over the considered OIFITS files.

Type:

OIVis2

t3

Object representing data in the OI_T3 tables concatenated over the considered OIFITS files.

Type:

OIT3

flux

Object representing data in the OI_FLUX tables concatenated over the considered OIFITS files.

Type:

OIFlux

Warning

Make sure the data in different files is consistent in terms of target and setup. E.g. if first file read in uses differential instead of absolute visibilities in the OI_VIS table, all other files should also contain differential visibilities. If you wish to model observations taken with different instrument setup simultaneously, different OIData objects should be created for each setup.

Notes

The constructor simply initiates all properties of the instance to None. Data is meant to be read in using the from_oifits method instead.

filter(name: str | list[str], range: tuple[float, float] | list[tuple[float, float]]) → None

Filter data.

Filter out data based on user input range on quantity of interest or on if data has been flagged if name='flag'.

Parameters:

• name (str or list of str) – Name(s) of the variables to be filtered (e.g. ‘visamp’). Can also pass ‘flag’ in order to filter out flagged data.

• range (tuple of float or list of tuple of float) – Range(s) of the variables which we want to cut. E.g. name=’visamp’ & range=(0.01, 0.1) -> will filter out all data with visibility between 0.01 and 0.1.

Notes

This function applies to all relevant types of stored data. I.e. if the OIData object contains both squared visibilities and triple products, and you filter based on ‘eff_wave’, filtering will be applied to both types of observables.

from_oifits(data_dir: str, data_file: str, ft_only: bool = False) → None

Read in data from OIFITS files.

Master function to read in OIFITS data, including the use of wildcards to read in data from multiple files simultaneously.

Parameters:

• data_dir (str) – Directory containing the OIFITS files.

• data_file (str) – Filename or wildcard pattern to match the OIFITS files.

• ft_only (bool, optional) – Whether to only read in fringe tracker data, by default False. If True, only science data is considered.

Warning

The read-in metadata on the instrument setup, target and array (i.e. the primary table header, OI_TARGET, OI_ARRAY) and choice of observables (absolute, differential, coherent flux, etc.) are read in only from the first considered file. Make sure the data in simultaneously read-in files are thus consistent in terms of setup. This allows the consistent merging of OI_VIS, OI_VIS2, OI_T3 and OI_FLUX tables into single consistent Python objects. If you wish to model observations taken with different instrument setup simultaneously, different OIData objects should be created for each setup.

plot_data(dname: str, xname: str, yname: str, ename: str | None = None, cname: str | None = None, xlim: tuple[float, float] | None = None, ylim: tuple[float, float] | None = None, per_baseline: bool = False, ptype: str = 'line', show_plots: bool = True, fig_dir: str | None = None, logx: bool = False, logy: bool = False, logc: bool = False) → Figure

Plot data.

Master plotting function to plot data contained in the OIData object.

Parameters:

• dname (str) – Name of the type of OI data table to plot. Can be ‘vis’, ‘vis2’, ‘t3’ and ‘flux’.

• xname (str) – Name of the data to be plotted on the x axis. Can be any of the names of the np.ndarray object attributes corresponding to dtype, except ‘flag’.

• yname (str) – Name of the data to be plotted on the y axis. Can be any of the names of the np.ndarray object attributes corresponding to dtype, except ‘flag’.

• ename (str, optional) – Name of the data to be used to plot errorbars. None by default, meaning no errorbars.

• cname (str, optional) – Name of the data used to colour the plot. Can be any of the names of the np.ndarray object attributes corresponding to dtype, except ‘flag’, but also ‘baseline’ in order to colour data by the baseline pair/triangle/telescope. None by default, in which case all datapoints will have the same color.

• xlim (tuple of float, optional) – Limits for the x axis, by default None.

• ylim (tuple of float, optional) – Limits for the y axis, by default None.

• per_baseline (bool, optional) – Whether to make a separate plot per baseline pair/triangle/telescope. By default set to False, meaning all data is put into a separate plot.

• ptype (str, optional) – Plotting type, by default set to ‘line’ to plot a line for each baseline pair/triangle /telescope. Can be set to ‘scatter’ to instead plot point separately in a scatterplot.

• show_plots (bool, optional) – Whether to show the plots, by default True.

• fig_dir (str, optional) – Directory of where to save the figure. None by default, in which case no figure will be saved.

• logx (bool, optional) – Whether to plot x axis in log scale, by default False.

• logy (bool, optional) – Whether to plot y axis in log scale, by default False.

• logc (bool, optional) – Whether to plot the color scale in log scale, by default False.

Returns:

The matplotlib figure, which can then be further manipulated.

Return type:

plt.Figure

plot_uv(dname)

Make a plot of the uv coverage for the data.

Parameters:

dname (str) – Name of the type of OI data table whose uv coverage is plotted. Can be ‘vis’, ‘vis2’ or ‘t3’.

class distroi.data.oi_data.OIFlux

Bases: object

Class to describe OI_FLUX table data.

Class to describe the concatenated data contained in OI_FLUX tables of multiple OIFITS files.

header

Header dictionary.

Type:

dict

time

Time of observations in seconds.

Type:

np.ndarray

mjd

Modified Julian Date of observations.

Type:

np.ndarray

int_time

Integration time in seconds.

Type:

np.ndarray

fluxdata

Measured flux; units specified in header.

Type:

np.ndarray

fluxerr

Data on measured flux.

Type:

np.ndarray

flag

Array of booleans denoting whether data has been flagged by the reduction or not.

Type:

np.ndarray

telescope_dict

Dictionary mapping index integers to the strings describing the telescope used for the measurement. Only used if ‘CALSTAT = U’, in which the uncalibrated flux spectrum is stored per telescope (see OIFITS 2 standard). If ‘CALSTAT = C’, will instead remain None.

Type:

dict

telescope_idx

Telescope index of the data (to be used with telescope_dict). Only used if ‘CALSTAT = U’, in which case the uncalibrated flux spectrum is stored per telescope (see OIFITS 2 standard). If ‘CALSTAT = C’, will instead remain None.

Type:

np.ndarray

eff_wave

Effective wavelength of the data; units m.

Type:

np.ndarray

eff_band

Effective wavelength bandwidth of data; units m.

Type:

np.ndarray

class distroi.data.oi_data.OIT3

Bases: object

Class to describe OI_T3 table data.

Class to describe the concatenated data contained in OI_T3 tables of multiple OIFITS files.

header

Header dictionary.

Type:

dict

time

Time of observations in seconds.

Type:

np.ndarray

mjd

Modified Julian Date of observations.

Type:

np.ndarray

int_time

Integration time in seconds.

Type:

np.ndarray

t3amp

Triple product amplitude.

Type:

np.ndarray

t3amperr

Error on triple product amplitude.

Type:

np.ndarray

t3phi

Triple product phase (closure phase) in degrees.

Type:

np.ndarray

t3phierr

Error on triple product phase (closure phase).

Type:

np.ndarray

u1coord

u coordinate of the data’s first baseline in unit m.

Type:

np.ndarray

v1coord

v coordinate of the data’s first baseline in unit m.

Type:

np.ndarray

u2coord

u coordinate of the data’s second baseline in unit m.

Type:

np.ndarray

v2coord

v coordinate of the data’s second baseline in unit m.

Type:

np.ndarray

flag

Array of booleans denoting whether data has been flagged by the reduction or not.

Type:

np.ndarray

baseline_dict

Dictionary mapping baseline index integers to the strings describing the baseline.

Type:

dict

baseline_idx

Baseline index of the data (to be used with baseline_dict).

Type:

np.ndarray

eff_wave

Effective wavelength of the data; units m.

Type:

np.ndarray

eff_band

Effective wavelength bandwidth of data; units m.

Type:

np.ndarray

u3coord

u coordinate of the data’s third baseline in unit m.

Type:

np.ndarray

v3coord

v coordinate of the data’s third baseline in unit m.

Type:

np.ndarray

u1fcoord

u coordinate spatial frequency of first baseline; units cycle rad^-1.

Type:

np.ndarray

v1fcoord

v coordinate spatial frequency of first baseline; units cycle rad^-1.

Type:

np.ndarray

u2fcoord

u coordinate spatial frequency of second baseline; units cycle rad^-1.

Type:

np.ndarray

v2fcoord

v coordinate spatial frequency of second baseline; units cycle rad^-1.

Type:

np.ndarray

u3fcoord

u coordinate spatial frequency of third baseline; units cycle rad^-1.

Type:

np.ndarray

v3fcoord

v coordinate spatial frequency of third baseline; units cycle rad^-1.

Type:

np.ndarray

base_max

Size of the longest baseline in m.

Type:

np.ndarray

spat_freq_max

Spatial frequency of the longest baseline in cycles per radian.

Type:

np.ndarray

Notes

------

The third baseline is chosen following the convention that the triple product is calculated as V1 x V2 x V3*,

with V3* being the conjugate of the third baseline's visibility.

class distroi.data.oi_data.OITarget

Bases: object

Class to describe the OI_TARGET table of an OIFITS file.

header

Header dictionary.

Type:

dict

target_id

Target ID number.

Type:

int

target

Target name.

Type:

str

equinox

Equinox in years.

Type:

float

raep0

Target right ascension at equinox in deg.

Type:

float

decep0

Target declination at equinox in deg.

Type:

float

ra_err

Error on right ascension.

Type:

float

dec_err

Error on declination.

Type:

float

sysvel

Systemic radial velocity in m/s.

Type:

float

veltyp

Reference for radial velocity (e.g. “LSR”).

Type:

str

veldef

Definition for radial velocity (e.g. “OPTICAL”).

Type:

str

pmra

Right ascension proper motion in deg/yr.

Type:

float

pmdec

Declination proper motion in deg/yr.

Type:

float

pmra_err

Error on right ascension proper motion.

Type:

float

pmdec_err

Error on declination proper motion.

Type:

float

parallax

Parallax in degrees.

Type:

float

para_err

Error on parallax.

Type:

float

spectyp

Target spectral type.

Type:

str

Notes

------

Only read in once when using `from_oifits`, since we assume the target will be the same for all considered

OIFITS files.

class distroi.data.oi_data.OIVis

Bases: object

Class to describe OI_VIS table data.

Class to describe the concatenated data contained in OI_VIS tables of multiple OIFITS files.

header

Header dictionary.

Type:

dict

time

Time of observations in seconds.

Type:

np.ndarray

mjd

Modified Julian Date of observations.

Type:

np.ndarray

int_time

Integration time in seconds.

Type:

np.ndarray

visamp

Visibility amplitude. Units depend on type of visibility (e.g. coherent flux vs. normalized visibility). In case ‘correlated flux’ and TUNIT keyword not specified in header -> assumed to be in Jansky.

Type:

np.ndarray

visamperr

Error on visibility amplitude.

Type:

np.ndarray

visphi

Visibility phase in degrees.

Type:

np.ndarray

visphierr

Error on visibility phase.

Type:

np.ndarray

rvis

Real part of complex coherent flux; units defined in header.

Type:

np.ndarray

rviserr

Error on real part of complex coherent flux.

Type:

np.ndarray

ivis

Imaginary part of complex coherent flux; units defined in header.

Type:

np.ndarray

iviserr

Error on imaginary part of complex coherent flux.

Type:

np.ndarray

ucoord

u coordinate of the data in unit m.

Type:

np.ndarray

vcoord

v coordinate of the data in unit m.

Type:

np.ndarray

flag

Array of booleans denoting whether data has been flagged by the reduction or not.

Type:

np.ndarray

baseline_dict

Dictionary mapping baseline index integers to the strings describing the baseline.

Type:

dict

baseline_idx

Baseline index of the data (to be used with baseline_dict).

Type:

np.ndarray

eff_wave

Effective wavelength of the data; units m.

Type:

np.ndarray

eff_band

Effective wavelength bandwidth of data; units m.

Type:

np.ndarray

ufcoord

u coordinate spatial frequency; units cycle rad^-1.

Type:

np.ndarray

vfcoord

v coordinate spatial frequency; units cycle rad^-1.

Type:

np.ndarray

base

Size of the baseline in m.

Type:

np.ndarray

spat_freq

Spatial frequency in cycles per radian.

Type:

np.ndarray

class distroi.data.oi_data.OIVis2

Bases: object

Class to describe OI_VIS2 table data.

Class to describe the concatenated data contained in OI_VIS2 tables of multiple OIFITS files.

header

Header dictionary.

Type:

dict

time

Time of observations in seconds.

Type:

np.ndarray

mjd

Modified Julian Date of observations.

Type:

np.ndarray

int_time

Integration time in seconds.

Type:

np.ndarray

vis2data

Squared visibility amplitude. Always normalized.

Type:

np.ndarray

vis2err

Error on squared visibility amplitude.

Type:

np.ndarray

ucoord

u coordinate of the data in unit m.

Type:

np.ndarray

vcoord

v coordinate of the data in unit m.

Type:

np.ndarray

flag

Array of booleans denoting whether data has been flagged by the reduction or not.

Type:

np.ndarray

baseline_dict

Dictionary mapping baseline index integers to the strings describing the baseline.

Type:

dict

baseline_idx

Baseline index of the data (to be used with baseline_dict).

Type:

np.ndarray

eff_wave

Effective wavelength of the data; units m.

Type:

np.ndarray

eff_band

Effective wavelength bandwidth of data; units m.

Type:

np.ndarray

ufcoord

u coordinate spatial frequency; units cycle rad^-1.

Type:

np.ndarray

vfcoord

v coordinate spatial frequency; units cycle rad^-1.

Type:

np.ndarray

base

Size of the baseline in m.

Type:

np.ndarray

spat_freq

Spatial frequency in cycles per radian.

Type:

np.ndarray