ConversionMap

ConversionMap(source_unit=None, target_unit=None, uid=None, name=None)

Abstract base class for coordinate conversion maps.

A ConversionMap transforms coordinates from one representation to another. Maps are callable and support both scalar and array inputs.

The key methods are: - call(value): Convert a single value or array - inverse(): Get the inverse map (if invertible)

Attributes

Name	Type	Description
id	str	Unique identifier for this map instance.
source_unit	TimeUnit | None	The unit of input coordinates (optional).
target_unit	TimeUnit | None	The unit of output coordinates (optional).

Examples

>>> # Create a map that doubles values
>>> linear = LinearMap(scalar=2.0)
>>> linear(5.0)
10.0

>>> # Maps are callable
>>> linear(np.array([1.0, 2.0, 3.0]))
array([2., 4., 6.])

>>> # Get the inverse
>>> inv = linear.inverse()
>>> inv(10.0)
5.0

Methods

Name	Description
convert_array	Convert an array of values.
from_dict	Deserialize a map from a dictionary.
inverse	Return the inverse of this map.
matches_selector	Return whether a user conversion-map selector addresses this map.
then	Compose this map with another (this first, then other).
to_dict	Serialize the map to a dictionary.

convert_array

ConversionMap.convert_array(values, **kwargs)

Convert an array of values.

This is the public API for array conversion, used by the timestamp system and other batch operations. It delegates to _convert_array().

All ConversionMap subclasses support efficient array operations through this method. Linear maps use NumPy broadcasting, TableMaps use np.interp, and composite maps delegate to their sub-maps.

Parameters

Name	Type	Description	Default
values	NDArray[Any]	NumPy array of values to convert.	required
**kwargs	Any	Subclass-specific arguments.	{}

Returns

Name	Type	Description
	NDArray[Any]	NumPy array of converted values with same shape as input.

Examples

>>> linear = LinearMap(scalar=2.0, offset=1.0)
>>> linear.convert_array(np.array([0.0, 1.0, 2.0]))
array([1., 3., 5.])

>>> tempo_map = TableMap.from_tempo_changes([0, 960], [120, 60], 480)
>>> tempo_map.convert_array(np.array([0, 480, 960]))
array([0.  , 0.5 , 1.5])

from_dict

ConversionMap.from_dict(data)

Deserialize a map from a dictionary.

Dispatches to the concrete subclass named by data["type"] using the self-registering class registry populated by __init_subclass__.

Parameters

Name	Type	Description	Default
data	dict[str, Any]	Dictionary representation.	required

Returns

Name	Type	Description
	ConversionMap[Any]	A ConversionMap instance.

Raises

Name	Type	Description
	ValueError	If the type is missing or unknown.
	TypeError	If the registered class does not override from_dict, which would otherwise recurse indefinitely.

inverse

ConversionMap.inverse()

Return the inverse of this map.

Returns

Name	Type	Description
	Self	A new ConversionMap that reverses this transformation.

Raises

Name	Type	Description
	NotImplementedError	If the map is not invertible.

matches_selector

ConversionMap.matches_selector(key)

Return whether a user conversion-map selector addresses this map.

Subclasses that are addressed by other identifiers (for example, InterpolationMap by its source timeline id) should override this and extend the match.

Parameters

Name	Type	Description	Default
key	str	A selector string from a conversion-map specification.	required

Returns

Name	Type	Description
	bool	True if key equals this map’s id or name.

then

ConversionMap.then(other)

Compose this map with another (this first, then other).

Parameters

Name	Type	Description	Default
other	ConversionMap[Any]	The map to apply after this one.	required

Returns

Name	Type	Description
	ConversionMap[Any]	A ChainMap that applies both maps in sequence.

to_dict

ConversionMap.to_dict()

Serialize the map to a dictionary.

Subclasses should call super().to_dict() and add their parameters; rational parameters go through :func:~timetoalign.core.rational_to_wire so that the whole dictionary stays JSON-serializable.

The map’s name is always emitted, and every subclass from_dict passes it back to the constructor, so a custom name survives the round trip.

Returns

Name	Type	Description
	dict[str, Any]	Dictionary representation of the map.