Skip to content

virgil.night_summaries

Per-night, per-peak (position, velocity, flux) summaries of a binary's companion, fitted at visibility level with linear motion over the whole night.

Per-night, per-peak (position, velocity, flux) summaries at visibility level.

Provisional

May change in any 0.4.x release without a deprecation cycle.

Each night's companion is fitted peak by peak with linear motion over the whole night, p(t) = p + v (t - t̄), on the visibilities with the noise model of the data (gains, closure offsets and spanning gain modes marginalized as in whitened_residuals). The summary of a peak is the mean and covariance of (p, v, ln f) at the quoted errors, with the per-block counts, minimum χ² and Hessians that rescale it to another error scale in closed form (for data without gains or closure offsets, where a scale factors out of the covariance). For frames of error σ the velocity variance is σ² / Σ_j (t_j - t̄)²; in terms of the night position's error σ_p² = σ² / N it is 12 σ_p² / span² for uniform sampling. A short or faint night's velocity therefore carries no weight and no threshold is needed.

DELTA = 0.001 module-attribute

NightSummary dataclass

One night's catalogue of peaks.

Attributes:

Name Type Description
t_ref float

The night's reference time t̄ (MJD), the mean frame time.

t_ss float

Σ_j (t_j - t̄)² over the night's frames (days²); 0 for one frame.

n_frames int

Number of frames (exposures) t_ss sums over.

blocks tuple of str

The error blocks of NightPeak.n, "vis", "phi", ...

peaks tuple of NightPeak

Converged peaks, best first. Empty if none converged.

loglike_null float

The night's log likelihood with no companion.

offsets tuple of float, optional

The frame times t_j - t̄ (days), n_frames of them. None means uniform spacing with the sum of squares t_ss.

weights tuple of float, optional

The weight of each frame in the (p, v) least-squares fit. None means equal weights, which the variances of covariance assume.

t_ref instance-attribute

t_ss instance-attribute

n_frames instance-attribute

blocks instance-attribute

peaks instance-attribute

loglike_null instance-attribute

offsets = None class-attribute instance-attribute

weights = None class-attribute instance-attribute

__init__(t_ref, t_ss, n_frames, blocks, peaks, loglike_null, offsets=None, weights=None)

__len__()

frame_offsets()

The frame offsets t_j - t̄ (days): (n_frames,).

frame_weights()

The frame weights of the (p, v) fit: (n_frames,).

projection()

The (2, n_frames) map from the companion's frame positions to the night's (p̂, v̂): the weighted least-squares fit of p + v (t_j - t̄), exact for the positions under these scalar frame weights. It matches the visibility fit only to first order in the track's departure from a line: the fit weights each frame by its own information (rows, errors, baseline orientation), which the equal default does not. One frame, or a zero t_ss, gives the instantaneous position and a zero row for the velocity (taken from the state).

covariance(peak, scale=1.0, jitter=0.0)

peak's covariance at error scale with a jitter (mas), independent per frame, added in quadrature to every frame's position error: the night position (at t̄) gains jitter² / n_frames and the velocity jitter² / t_ss (infinite for one frame).

NightPeak dataclass

One peak of one night.

Attributes:

Name Type Description
mean ndarray

(dra, ddec, vra, vdec, ln f): position (mas) at the night's reference time, velocity (mas/day, East and North) and log flux ratio.

cov ndarray

(5, 5) covariance of mean at the quoted errors (a direction the night does not constrain gets a variance of 1 / (eps λ_max)).

loglike float

Log likelihood of the night at the peak, normalization included.

n, chi2 ndarray

Per block (NightSummary.blocks): independent observables and minimum χ² on the quoted errors.

hessian ndarray

(blocks, 5, 5) Hessians of ½ χ² per block at the peak.

rescalable bool

Whether precision and log_scale rescale the errors in closed form: false with gains or closure offsets, whose covariance s² D + U Uᵀ a scale does not factor.

mean instance-attribute

cov instance-attribute

loglike instance-attribute

n instance-attribute

chi2 instance-attribute

hessian instance-attribute

rescalable = True class-attribute instance-attribute

__init__(mean, cov, loglike, n, chi2, hessian, rescalable=True)

precision(scale=1.0)

Σ⁻¹ with the errors of block g multiplied by scale[g] (a number or one per block).

covariance(scale=1.0)

Σ at error scale (see precision).

log_scale(scale)

ln L_j(s) - ln L_j(1) for block scales s: -Σ_g [n_g ln s_g + (χ²_g / 2)(s_g⁻² - 1)] (the mean is held at its s = 1 value).

night_summaries(data, positions, *, amp_range=None)

Each night's per-peak linear-motion fit on the visibilities.

The peaks start from each night's catalogue (EpochPositions.peaks) at zero velocity and are refined, in float64, over the whole night with the primary of positions (no half-night split, so closure offsets and spanning gain modes are kept). A refinement that does not converge is dropped; peaks that converge to one point are merged.

Parameters:

Name Type Description Default
data Epochs or sequence of OIData

The nights, in the order of positions. Each needs sample times (mjd).

required
positions EpochPositions

The nights' peak catalogues and the primary diameter.

required
amp_range tuple of float

Profile one visibility amplitude per night in this range, as the orbit fit does (default None).

None

Returns:

Type Description
tuple of NightSummary

keep_peaks(summaries, log_outlier, delta=DELTA)

The peaks the position-level likelihood needs.

A peak is kept iff (1 - ε_lo) L_j ≥ δ ε_lo e^{b_k}: an orbit through it contributes at best (1 - ε) L_j to the night's mixture factor (1 - ε) e^{ℓ_k} + ε e^{b_k}, with no Occam factor. ε_lo is the smallest Gauss–Jacobi node of the EPS_PRIOR integral of ε, with n = ⌈(K + 1) / 2⌉ nodes for K nights.

Parameters:

Name Type Description Default
summaries sequence of NightSummary required
log_outlier array - like

b_k, each night's log outlier density, on the likelihood's normalization (NightPeak.loglike).

required
delta float

Reporting precision (default DELTA).

DELTA

Returns:

Type Description
tuple of NightSummary