OIFITS Handling

OIdata{T<:AbstractFloat}

Central data container produced by readoifits. All observable arrays are flat vectors of length nobs; UV coordinates are stored in a 2×nuv matrix.

Observable arrays

• v2, v2_err — squared visibilities and errors
• v2_baseline, v2_lam, v2_dlam, v2_mjd, v2_flag — baseline (m), λ (m), Δλ (m), MJD, flag
• t3phi, t3phi_err, t3amp, t3amp_err — closure phases (deg) and triple amplitudes
• t3_baseline — geometric-mean baseline (m); t3_maxbaseline — longest side (m)
• t3_lam, t3_dlam, t3_mjd, t3_flag
• visamp, visamp_err, visphi, visphi_err — complex visibility amplitude and phase (deg)
• vis_baseline, vis_lam, vis_dlam, vis_mjd, vis_flag
• flux, flux_err, flux_lam, flux_dlam, flux_mjd, flux_flag
• flux_sta_index — station index for each flux point; 0 means calibrated (OI_FLUX CALSTAT=C)
• flux_calibrated — true if OI_FLUX has CALSTAT="C" (calibrated source spectrum / SED)

UV plane

• uv — 2×nuv matrix of (u, v) spatial frequencies in cycles/m (i.e. baseline/λ)
• uv_lam, uv_dlam, uv_mjd, uv_baseline
• indx_v2, indx_vis — index of each V²/vis point into the UV array
• indx_t3_1, indx_t3_2, indx_t3_3 — UV indices for the three legs of each triangle

Station / telescope metadata

• sta_name, tel_name, sta_index — station names, telescope names, station indices
• v2_sta_index — 2×nv2 matrix; t3_sta_index — 3×nt3 matrix; vis_sta_index — 2×nvis

Sizes

• nv2, nt3amp, nt3phi, nvisamp, nvisphi, nflux, nuv

Correlation matrices (from OI_CORR; empty sparse matrices when absent)

• v2_corr, v2_corr_idx — V² correlation matrix and per-point 1-based index
• t3amp_corr, t3amp_corr_idx, t3phi_corr, t3phi_corr_idx
• visamp_corr, visamp_corr_idx, visphi_corr, visphi_corr_idx
• flux_corr, flux_corr_idx
• *_corr_idx[i] == 0 means point i has no associated correlation row.

Other

• mean_mjd::Float64 — mean MJD of the bin (always Float64 regardless of T)
• filename — path to the originating OIFITS file

readoifits(oifitsfile; kwargs...) -> Array{OIdata{T}, 2}

Read an OIFITS file and return a 2-D array of OIdata{T} indexed as [nwavbin, ntimebin]. The simplest call returns a 1×1 array containing all data in a single bin.

Keyword arguments

Target selection

• targetname — select a single target by name. Default: all targets combined.

Spectral / temporal binning

• spectralbin — vector of [λ_min, λ_max] windows in metres. Default: single bin spanning all wavelengths.
• temporalbin — vector of [mjd_min, mjd_max] windows. Default: single bin spanning all epochs.
• polychromatic — if true, derive one spectral bin per instrument channel using midpoints between adjacent channel centres as boundaries. Overrides spectralbin.
• splitting — force multi-bin mode even when bin vectors equal [[]].
• get_specbin_file — auto-derive spectral bins from the file. Default: true.
• get_timebin_file — auto-derive temporal bins from the file. Default: true.

Observable selection

• use_vis, use_v2, use_t3, use_flux — load each observable type. Default: all true.

Quality filtering

• filter_bad_data — apply quality cuts on load. Default: true.
• force_full_vis — require both visamp and visphi to be valid. Default: false.
• force_full_t3 — require both t3amp and t3phi. Default: false.
• cutoff_minv2, cutoff_maxv2 — V² range cut. Default: (-1, 2.0).
• cutoff_mint3amp, cutoff_maxt3amp — T3amp range cut. Default: (-1.0, 1.5).
• filter_v2_snr_threshold — minimum |V²/σ|. Default: 0.01.
• special_filter_diffvis — differential visibility mode: keep only vis points common across all spectral bins.

UV deduplication

• redundance_remove — merge UV points closer than uvtol. Default: true.
• uvtol — merge radius in cycles/rad (i.e. B/λ). Default: 200.0.

Numeric precision

• T — element type for all numeric arrays. Use Float32 for ~50% memory reduction. Default: Float64.

Output

• warn — print warnings about non-standard files. Default: true.
• verbose — print summary of loaded tables. Default: false.

Example

data = readoifits("mystar.oifits")                         # all data, single bin
data = readoifits("mystar.oifits"; polychromatic=true)     # one bin per channel
data = readoifits("mystar.oifits"; T=Float32)              # half memory
data = readoifits("multi.oifits"; targetname="Betelgeuse") # one target

readoifits_multiepochs(oifitsfiles; kwargs...) -> (nepochs, tepochs, data)

Read a list of OIFITS files, one per epoch, and return:

• nepochs — number of files
• tepochs::Vector{Float64} — mean MJD of each epoch
• data::Vector{OIdata{T}} — one OIdata per epoch (single spectral bin each)

Prints a summary line per file. Passes filter_bad_data and force_full_t3 through to readoifits.

readoifits_multicolors(oifitsfiles; kwargs...) -> Vector{OIdata{T}}

Read a list of OIFITS files, one per waveband, and return a Vector{OIdata{T}} (one element per file, single spectral bin each). Prints a summary line per file.

filter_data(data, indexes_to_discard) -> OIdata

Return a deep copy of data with the specified points removed. indexes_to_discard must be the five-element vector [uv_bad, vis_bad, v2_bad, t3_bad, flux_bad] returned by set_data_filter. UV points that become unreferenced after removing observables are pruned automatically and all index arrays are remapped.

Example

idx = set_data_filter(data[1,1]; filter_bad_data=true, baseline_range=[5e6, 300e6])
clean = filter_data(data[1,1], idx)

set_data_filter(data; kwargs...) -> [uv_bad, vis_bad, v2_bad, t3_bad, flux_bad]

Compute lists of indices to discard from a loaded OIdata bin without modifying it. Pass the result to filter_data to obtain a filtered copy.

Keyword arguments

• wav_range — wavelength window(s) in metres, e.g. [1.6e-6, 1.8e-6] or a vector of windows [[1.6e-6,1.8e-6],[2.0e-6,2.4e-6]]. Default: keep all.
• mjd_range — MJD window(s), same format. Default: keep all.
• baseline_range — [min, max] baseline in cycles/m. Default: keep all.
• filter_bad_data — apply quality cuts (flags, NaN, SNR, amplitude range). Default: false.
• filter_vis, filter_v2, filter_t3amp, filter_t3phi, filter_flux — enable cuts per observable type.
• cutoff_minv2, cutoff_maxv2 — V² range cut. Default: (-1, 2.0).
• cutoff_mint3amp, cutoff_maxt3amp — T3 amplitude range cut. Default: (-1.0, 1.5).
• filter_v2_snr_threshold — minimum |V²/σ| to keep. Default: 0.01.
• force_full_vis — require both amplitude and phase to be valid (default: either).
• force_full_t3 — require both T3amp and T3phi to be valid (default: either).
• special_filter_diffvis — enable differential visibility filtering mode.
• uv_bad — pre-supplied list of UV indices to remove.
• filter_visphi, filter_visamp — enable visibility phase/amplitude filtering.

Returns [uv_bad, vis_bad, v2_bad, t3_bad, flux_bad] — five Vector{Int64} of indices to discard.

pmoired_to_julia(s) -> String

Convert a PMOIRED Python dict literal string to an equivalent Julia Dict literal string. Handles nested dicts, expression strings with $ references, single-quoted strings, Python boolean/None literals, and list literals.

Transformation rules applied: { ... } -> Dict( ... ) 'key': value -> "key" => value (outside string literals) : -> => (outside string literals, single colon only) 'plain string' -> "plain string" 'expr with ref' -> raw"expr with ref" (raw string prevents interpolation) True / False -> true / false None -> nothing

Example

# Python / PMOIRED:
param = {
    'star,ud':    3.2,
    'star,f':     0.7,
    'ring,udout': '$star,ud * 8',
    'ring,f':     '1 - $star,f',
    'ring,incl':  30.0,
}
fitOnly = ['star,ud', 'star,f', 'ring,udout', 'ring,f']

# Generated Julia:
param = Dict(
    "star,ud"    => 3.2,
    "star,f"     => 0.7,
    "ring,udout" => raw"$star,ud * 8",
    "ring,f"     => raw"1 - $star,f",
    "ring,incl"  => 30.0,
)
fitOnly = ["star,ud", "star,f", "ring,udout", "ring,f"]

pmoired_to_julia_file(infile, outfile)

Read a Python/PMOIRED notebook snippet from infile, convert it, write to outfile. Lines that look like param = {...} or fitOnly = [...] are converted; other lines are passed through.

recenter(x; mask=[], max=false)

Recenter an image by circular shifting so the centroid (or peak if max=true) is at the image center. Works on 1D (vectorized square image) or 2D arrays. If mask is provided, the centroid is computed from the mask instead.

magnitudes_from_simbad(targetname)

Query SIMBAD for photometric magnitudes (V, J, H, K, L, M, N). Returns a Dict{String,Float64} with band names as keys. Missing magnitudes are set to NaN.