MatchLine

alignment.MatchLine(source_timeline_id, stamps=list())

Ordered sequence of MatchStamps for a source timeline.

A MatchLine collects all synchronised timestamps that mention a given source timeline, orders them by coordinate on that timeline, and exposes get_coordinate_pairs() to extract the (source_coord, target_coord) table consumed by WarpMap.

Attributes

Name Type Description
source_timeline_id str The timeline whose coordinates define the ordering of the stamps.
stamps list[MatchStamp] MatchStamps sorted by coordinate on source_timeline_id.

Examples

>>> line = MatchLine.from_claims(
...     claims=claims,
...     source_timeline_id="score",
... )
>>> pairs = line.get_coordinate_pairs("audio")
>>> pairs
[(0.0, 0.0), (100.0, 45.5), (200.0, 91.0)]

See Also

timetoalign.MatchGraph timetoalign.MatchStamp

Methods

Name Description
from_claims Build a MatchLine from claims via a MatchGraph.
from_dict Deserialize from dictionary.
from_graphs Build a MatchLine from multiple MatchGraphs.
get_coordinate_pairs Extract (source_coord, target_coord) pairs for a target timeline.
save_as Export this MatchLine to a file.
target_timeline_ids All target timelines appearing in at least 2 stamps.
to_dict Serialize to dictionary for storage.

from_claims

alignment.MatchLine.from_claims(
    claims,
    source_timeline_id,
    *,
    groups=None,
    timeline_to_group=None,
    timeline_ids=None,
    id_pattern=None,
    include_domains=None,
    include_units=None,
)

Build a MatchLine from claims via a MatchGraph.

Constructs a MatchGraph from the supplied claims, optionally extends it to groups, extracts MatchStamps, and orders them by coordinate on the source timeline.

Parameters

Name Type Description Default
claims list[MatchClaim] List of MatchClaims to resolve. required
source_timeline_id str The timeline whose coordinates define the ordering. required
groups dict[str, TimelineGroup] | None Dict of group_id -> TimelineGroup for group extension. If None, no group extension is performed. None
timeline_to_group dict[str, str] | None Dict of timeline_id -> group_id. Required if groups is provided. None
timeline_ids set[str] | None Only extend to these timeline IDs. None
id_pattern str | None Regex filter for timeline IDs. None
include_domains set[Domain] | None Only extend to timelines in these domains. None
include_units set[TimeUnit] | None Only extend to timelines with these units. None

Returns

Name Type Description
MatchLine A MatchLine with stamps sorted by source coordinate.

from_dict

alignment.MatchLine.from_dict(data)

Deserialize from dictionary.

Parameters

Name Type Description Default
data dict[str, Any] Dict as produced by to_dict(). required

Returns

Name Type Description
MatchLine A new MatchLine.

from_graphs

alignment.MatchLine.from_graphs(graphs, source_timeline_id)

Build a MatchLine from multiple MatchGraphs.

Merges MatchStamps from several MatchGraphs (the Hendrix M6-M9 pattern) into a single ordered sequence. Duplicate stamps (same source coordinate) are deduplicated, keeping the stamp with the most timelines.

Parameters

Name Type Description Default
graphs list[MatchGraph] List of MatchGraphs to merge. required
source_timeline_id str The timeline whose coordinates define the ordering. required

Returns

Name Type Description
MatchLine A MatchLine with merged, deduplicated stamps sorted by
MatchLine source coordinate.

get_coordinate_pairs

alignment.MatchLine.get_coordinate_pairs(target_timeline_id)

Extract (source_coord, target_coord) pairs for a target timeline.

Only stamps that contain both the source and target timelines contribute to the result. Pairs are ordered by source coordinate.

Parameters

Name Type Description Default
target_timeline_id str The timeline to extract target coordinates for. required

Returns

Name Type Description
list[tuple[float, float]] List of (source_coord, target_coord) tuples, sorted by
list[tuple[float, float]] source coordinate.

Raises

Name Type Description
ValueError If target_timeline_id equals source_timeline_id.

save_as

alignment.MatchLine.save_as(filepath, *, format='match', context=None)

Export this MatchLine to a file.

Parameters

Name Type Description Default
filepath str | Path Output file path. If the extension matches a known format, the format is inferred (e.g. .match). required
format str Export format. Currently supported: "match". 'match'
context MatchFileContext | None Supplementary data for format-specific fields. Required for full .match export; if None, a minimal file with coordinate-only placeholder data is produced. None

Returns

Name Type Description
Path The resolved output path.

Raises

Name Type Description
ValueError If the format is not supported.

Examples

>>> line.save_as("output.match")  # minimal placeholder export
>>> line.save_as("output.match", context=ctx)  # rich export

target_timeline_ids

alignment.MatchLine.target_timeline_ids()

All target timelines appearing in at least 2 stamps.

A target timeline must appear in at least two stamps for interpolation (i.e., WarpMap construction) to be meaningful.

Returns

Name Type Description
set[str] Set of timeline IDs (excluding the source) that appear
set[str] in >= 2 stamps.

to_dict

alignment.MatchLine.to_dict()

Serialize to dictionary for storage.

Returns

Name Type Description
dict[str, Any] Dict with source_timeline_id and stamps.