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 |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Normalized noise specification from
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
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 |
Raises:
| Type | Description |
|---|---|
ValueError
|
Listing every validation problem found in |
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 |
required |
insname
|
str or sequence of str
|
Explicit instrument name(s) forwarded to
|
None
|
Returns:
| Type | Description |
|---|---|
OIData
|
Dataset with the specification's white scales and nuisance modes applied. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
NotImplementedError
|
If |
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 |
required |
spec
|
Mapping
|
Noise specification dictionary. |
required |
insname
|
str or sequence of str
|
Explicit instrument name(s) overriding any |
None
|
Returns:
| Type | Description |
|---|---|
bool
|
|