WarpMap

alignment.WarpMap(
    source_timeline_id,
    target_timeline_id,
    interpolation_map,
    source_unit=None,
    target_unit=None,
)

Bidirectional coordinate warping derived from alignment data.

A WarpMap converts coordinates from a source timeline to a target timeline (and back) using linear interpolation between anchor points extracted from a timetoalign.MatchLine.

Internally it delegates to an timetoalign.maps.interpolation.InterpolationMap for O(log n) lookup. The materialise() method produces a complete copy of a source timetoalign.Timeline with all coordinates warped to the target’s coordinate space.

Attributes

Name	Type	Description
source_timeline_id	str	ID of the source timeline.
target_timeline_id	str	ID of the target timeline.
interpolation_map	InterpolationMap	The underlying InterpolationMap for coordinate conversion.
source_unit	'TimeUnit | None'	Unit of the source timeline (optional, informational).
target_unit	'TimeUnit | None'	Unit of the target timeline (optional, informational).
n_anchors	int	Number of anchor points used for interpolation.

Examples

>>> warp = WarpMap.from_match_line(match_line, "audio")
>>> warp(100.0)           # score coord -> audio coord
45.5
>>> warp.inverse()(45.5)  # audio coord -> score coord
100.0

See Also

timetoalign.MatchLine timetoalign.InterpolationMap

Methods

Name	Description
convert_array	Convert an array of source coordinates to target coordinates.
from_coordinate_pairs	Build a WarpMap from explicit coordinate arrays.
from_dict	Deserialize from dictionary.
from_match_line	Build a WarpMap from a MatchLine’s coordinate pairs.
inverse	Return the cached inverse map with source and target swapped.
materialise	Produce a new Timeline with all contents warped to target coordinates.
to_dict	Serialize to dictionary.

convert_array

alignment.WarpMap.convert_array(values)

Convert an array of source coordinates to target coordinates.

from_coordinate_pairs

alignment.WarpMap.from_coordinate_pairs(
    source_timeline_id,
    target_timeline_id,
    source_coords,
    target_coords,
    *,
    source_unit=None,
    target_unit=None,
)

Build a WarpMap from explicit coordinate arrays.

This lower-level constructor is useful when coordinate pairs are already available (e.g. from a Parquet file or external alignment tool) and do not need to be extracted from a MatchLine.

Parameters

Name	Type	Description	Default
source_timeline_id	str	ID of the source timeline.	required
target_timeline_id	str	ID of the target timeline.	required
source_coords	list[float] | NDArray[np.floating[Any]]	Source coordinates. Duplicate coordinates are averaged when their targets are compatible; otherwise they raise an ambiguity error. Remaining coordinates must be strictly increasing.	required
target_coords	list[float] | NDArray[np.floating[Any]]	Corresponding target coordinates.	required
source_unit	'TimeUnit | None'	Unit of the source timeline (optional).	None
target_unit	'TimeUnit | None'	Unit of the target timeline (optional).	None

Returns

Name	Type	Description
	'WarpMap'	A new WarpMap.

Raises

Name	Type	Description
	ValueError	If fewer than 2 coordinate pairs, if source coordinates are ambiguous, or if the remaining source coordinates are not strictly increasing.

from_dict

alignment.WarpMap.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
	'WarpMap'	A new WarpMap.

from_match_line

alignment.WarpMap.from_match_line(
    match_line,
    target_timeline_id,
    *,
    source_unit=None,
    target_unit=None,
)

Build a WarpMap from a MatchLine’s coordinate pairs.

Extracts (source_coord, target_coord) pairs from the MatchLine for the given target timeline, deduplicates compatible chord coordinates, and constructs the interpolation map. A repeated source coordinate with materially different targets is rejected.

Parameters

Name	Type	Description	Default
match_line	'MatchLine'	The MatchLine providing ordered stamps.	required
target_timeline_id	str	The target timeline to warp towards.	required
source_unit	'TimeUnit | None'	Unit of the source timeline (optional).	None
target_unit	'TimeUnit | None'	Unit of the target timeline (optional).	None

Returns

Name	Type	Description
	'WarpMap'	A new WarpMap.

Raises

Name	Type	Description
	ValueError	If fewer than 2 coordinate pairs are available.
	ValueError	If target_timeline_id is not in the MatchLine’s target timelines.

inverse

alignment.WarpMap.inverse()

Return the cached inverse map with source and target swapped.

Returns

Name	Type	Description
	'WarpMap'	A WarpMap converting target coordinates back to source coordinates.

Raises

Name	Type	Description
	ValueError	If the target coordinates are not strictly monotonic (map is not invertible).

materialise

alignment.WarpMap.materialise(source_timeline)

Produce a new Timeline with all contents warped to target coordinates.

Creates a complete copy of the source timeline where every coordinate (events, children, regions) is converted by calling this map. The resulting timeline:

• Has length equal to the mapped source_timeline.length
• Preserves the source’s unit (unless target_unit differs)
• Contains warped copies of all events
• Contains warped copies of all children (recursively)
• Contains warped copies of all regions
• Carries an inverse WarpMap as a ConversionMap for traceability

Parameters

Name	Type	Description	Default
source_timeline	'Timeline'	The timeline to warp.	required

Returns

Name	Type	Description
	'Timeline'	A new Timeline with warped coordinates.

Raises

Name	Type	Description
	ValueError	If source_timeline.id does not match self.source_timeline_id.

to_dict

alignment.WarpMap.to_dict()

Serialize to dictionary.

Returns

Name	Type	Description
	dict[str, Any]	Dict with timeline IDs, units, and coordinate arrays.