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_alignment_anchors() for typed source-to-target pairs.

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",
... )
>>> anchors = line.get_alignment_anchors("audio")

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_alignment_anchors	Return typed source-to-target anchors in source order.
get_coordinate	Dispatch a scalar or plural exact source-position query.
get_coordinate_at	Resolve one exact source anchor to a target coordinate.
get_coordinates_at	Resolve exact source anchors for a coordinate collection.
get_coordinates_for	Return one stored timeline coordinate column.
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_alignment_anchors

alignment.MatchLine.get_alignment_anchors(target_timeline_id)

Return typed source-to-target anchors in source order.

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[AlignmentAnchor]	Typed alignment anchors sorted by source coordinate.

Raises

Name	Type	Description
	ValueError	If target_timeline_id equals source_timeline_id.

get_coordinate

alignment.MatchLine.get_coordinate(
    at,
    timeline_id=None,
    *,
    format='id_coordinate',
    rounding='round',
)

Dispatch a scalar or plural exact source-position query.

Parameters

Name	Type	Description	Default
at	CoordinateInput | CoordinateCollection	One exact source position or a coordinate collection.	required
timeline_id	str | None	Requested target timeline when required.	None
format	CoordinateFormat	Requested coordinate output format.	'id_coordinate'
rounding	Rounding	Integral projection mode.	'round'

Returns

Name	Type	Description
	CoordinateResult | list[CoordinateResult] | pd.Series	The selected precise-getter result.

get_coordinate_at

alignment.MatchLine.get_coordinate_at(
    at,
    timeline_id=None,
    *,
    format='id_coordinate',
    rounding='round',
)

Resolve one exact source anchor to a target coordinate.

Parameters

Name	Type	Description	Default
at	CoordinateInput	Exact source position.	required
timeline_id	str | None	Requested target timeline.	None
format	CoordinateFormat	Requested coordinate output format.	'id_coordinate'
rounding	Rounding	Integral projection mode.	'round'

Returns

Name	Type	Description
	CoordinateResult | pd.Series	The exact target coordinate projection.

get_coordinates_at

alignment.MatchLine.get_coordinates_at(
    at,
    timeline_id=None,
    *,
    format='id_coordinate',
    rounding='round',
)

Resolve exact source anchors for a coordinate collection.

Parameters

Name	Type	Description	Default
at	CoordinateCollection	Exact source positions to resolve atomically.	required
timeline_id	str | None	Requested target timeline.	None
format	CoordinateFormat	Requested coordinate output format.	'id_coordinate'
rounding	Rounding	Integral projection mode.	'round'

Returns

Name	Type	Description
	list[CoordinateResult] | pd.Series	A list of projections or canonical-value Series.

get_coordinates_for

alignment.MatchLine.get_coordinates_for(
    timeline_id,
    *,
    format='id_coordinate',
    rounding='round',
)

Return one stored timeline coordinate column.

Parameters

Name	Type	Description	Default
timeline_id	str	Timeline column to retrieve.	required
format	CoordinateFormat	Requested coordinate output format.	'id_coordinate'
rounding	Rounding	Integral projection mode.	'round'

Returns

Name	Type	Description
	list[CoordinateResult] | pd.Series	A list of projections or canonical-value Series.

Raises

Name	Type	Description
	KeyError	If the timeline does not occur in the line.

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.