Skip to content

virgil.noise_spec

Provisional

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

Declarative instrument noise specifications (virgil.noise_spec/1), validated and applied to an OIData without importing any instrument code. See Conventions.

Declarative instrument noise specifications (virgil.noise_spec/1).

Provisional

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

An instrument package measures departures from independent quoted errors and emits a plain dictionary, a JSON file, or an object implementing to_noise_spec() -> dict. This module validates the specification and applies it to an OIData through its existing with_error_scale, with_gains and with_closure_offsets methods; see conventions.

load_noise_spec(obj)

Load and validate a virgil.noise_spec/1 specification.

Parameters:

Name Type Description Default
obj Mapping, str, os.PathLike, or object with ``to_noise_spec()``

A specification dictionary, a path to its JSON file, or an object whose to_noise_spec() method returns the dictionary.

required

Returns:

Type Description
dict

Normalized noise specification from validate_noise_spec.

Raises:

Type Description
TypeError

If obj is none of the supported input forms.

ValueError

If the resolved specification fails validation.

validate_noise_spec(spec)

Validate and normalize a virgil.noise_spec/1 mapping.

Checks the major schema version, rejects unknown keys outside provenance, verifies value bounds across every group, and warns on plausible unit slips without mutating spec.

Parameters:

Name Type Description Default
spec Mapping

Raw noise specification dictionary.

required

Returns:

Type Description
dict

Normalized copy with schema, instrument, white, gains, closure_offsets, common_mode and provenance.

Raises:

Type Description
ValueError

Listing every validation problem found in spec.

apply_noise_spec(data, spec, *, insname=None)

Apply a validated virgil.noise_spec/1 specification to data.

Validates spec, refuses to apply onto data that already carry any marginalized nuisance modes, checks instrument_match, rescales quoted uncertainties on the observables present in data, and attaches marginalized gains and closure-phase offsets where the corresponding observables are present.

Parameters:

Name Type Description Default
data OIData

Prepared interferometric dataset without pre-existing gains, closure-phase offsets, or differential-phase nuisance modes.

required
spec Mapping

Noise specification dictionary conforming to virgil.noise_spec/1.

required
insname str or sequence of str

Explicit instrument name(s) forwarded to instrument_match.

None

Returns:

Type Description
OIData

Dataset with the specification's white scales and nuisance modes applied.

Raises:

Type Description
ValueError

If spec is invalid, if data already carries marginalized gains, closure-phase offsets, or differential-phase modes, or if data is incompatible with the requested nuisance modes.

NotImplementedError

If spec["common_mode"]["visphi"] is positive and data carries a "visphi" block.

instrument_match(data, spec, *, insname=None)

Check whether a dataset's recorded instrument matches spec.

Compares insname (or data["insname"] / getattr(data, "insname", None) when recorded and non-empty) against spec["instrument"] by case-insensitive exact or delimiter-bounded prefix matching so generic instrument names such as "GRAVITY" or "MATISSE" match sub-channel names such as "GRAVITY_SC" or "MATISSE_LM" without matching unrelated short names. Emits a UserWarning and returns False on mismatch, never raising.

Parameters:

Name Type Description Default
data OIData or Mapping

Dataset or record optionally carrying an insname attribute or key.

required
spec Mapping

Noise specification dictionary.

required
insname str or sequence of str

Explicit instrument name(s) overriding any insname on data (useful when OIFITS INSNAME metadata are read separately from OIData).

None

Returns:

Type Description
bool

True when the instruments match or either side is unrecorded; False when they disagree.