lacing.adapters.eaf

ELAN EAF adapter (Max Planck Institute’s annotation tool format).

EAF is the canonical format for tier-hierarchy annotation. Every Phase 0 adapter modeled flat tiers; this is the first that exercises lacing’s stereotype constraint model end-to-end (TIME_SUBDIVISION, INCLUDED_IN, SYMBOLIC_SUBDIVISION, SYMBOLIC_ASSOCIATION). See ANN-DOC §B and OSS-DOC tier-2.4.

Mapping

EAF ↔ lacing TIER_ID ↔ Tier.name PARENT_REF ↔ Tier.parent LINGUISTIC_TYPE_REF + CONSTRAINTS ↔ Tier.stereotype ALIGNABLE_ANNOTATION ↔ Annotation with MediaRef ANNOTATION_VALUE ↔ body['text'] MEDIA_DESCRIPTOR / MEDIA_URL ↔ MediaRef.asset_id (when present)

Time

EAF stores ALL times as integer milliseconds (the format requires it). We map directly to RationalTime(ms, rate=1000) — exact, no floats. Pass rate= to re-quantize to a different project rate (must be exact; raises LossyTimeConversionError otherwise).

Lossy on dump

  • ELAN provenance is at the document level (AUTHOR, DATE); per- annotation provenance and confidence are dropped.

  • REF_ANNOTATION (annotations referencing parent annotations rather than time slots) is not yet supported; the loader emits ALIGNABLE_ANNOTATION data only. Round-trip of REF annotations is Phase 2 work.

  • CV_REF controlled vocabularies are not preserved.

  • The ELAN default empty tier and default-lt linguistic type (auto-created by pympi) are filtered out on load if they have no annotations.

Spec: https://www.mpi.nl/tools/elan/EAFv3.0.xsd

lacing.adapters.eaf.dump(store: IntervalAnnotationStore, target: str | PathLike | None = None, *, pretty: bool = True, media_url: str | None = None, **_kwargs: Any) → bytes | None[source]

Write annotations as an ELAN EAF file.

Parameters:

  • store – Source store. Only annotations with MediaRef and a non-None interval are exported.

  • target – Output path. None = return bytes.

  • pretty – Pretty-print XML (default True).

  • media_url – Optional MEDIA_URL for MEDIA_DESCRIPTOR. If None and the store has annotations, use the first MediaRef’s asset_id.

lacing.adapters.eaf.load(source: str | bytes | PathLike, *, rate: int = 24000, asset_id: str | None = None, attribution: str = 'anonymous', drop_default_tier: bool = True, **_kwargs: Any) → IntervalAnnotationStore[source]

Load an ELAN EAF file into a MemoryStore.

Parameters:

  • source – Path or bytes containing EAF XML.

  • rate – Quantization rate (default DEFAULT_RATE). EAF times are milliseconds; conversions must be exact.

  • asset_id – Override media reference. None = use the first MEDIA_DESCRIPTOR/MEDIA_URL from the EAF, or the default.

  • attribution – Provenance.was_attributed_to value.

  • drop_default_tier – If True (default), filter out the empty default tier auto-created by pympi.