TableMap

TableMap(
    x_values,
    y_values,
    kind=InterpolationKind.linear,
    extrapolate=ExtrapolationPolicy.extrapolate,
    source_unit=None,
    target_unit=None,
    uid=None,
    name=None,
)

Lookup table with interpolation between anchor points.

A TableMap defines a mapping using explicit (x, y) pairs. Values between pairs are interpolated according to the specified method.

This is useful for: - Tempo-based time conversions (ticks to seconds with varying tempo) - Alignment anchors - Any non-linear monotonic mapping

Attributes

Name	Type	Description
x_values	`NDArray`[`np`.`floating`[`Any`]]	The input coordinates (must be strictly increasing).
y_values	`NDArray`[`np`.`floating`[`Any`]]	The corresponding output values.
kind	`InterpolationKind`	The interpolation method.
extrapolate	`InterpolationKind`	How to handle out-of-bounds inputs.

Examples

>>> # Simple tempo map: 0 ticks = 0 sec, 480 ticks = 0.5 sec, 960 ticks = 1.5 sec
>>> tempo_map = TableMap(
...     x_values=[0, 480, 960],
...     y_values=[0.0, 0.5, 1.5],
...     source_unit="ticks",
...     target_unit="seconds",
... )
>>> tempo_map(240)  # Interpolate: 0.25 sec
0.25
>>> tempo_map(720)  # Interpolate: 1.0 sec
1.0

>>> # Inverse map
>>> inverse = tempo_map.inverse()
>>> inverse(1.0)
720.0

Methods

Name	Description
from_dict	Deserialize from dictionary.
from_tempo_changes	Create a TableMap from MIDI-style tempo changes.
inverse	Return the inverse map (swap x and y).
to_dict	Serialize to dictionary.

from_dict

TableMap.from_dict(data)

Deserialize from dictionary.

from_tempo_changes

TableMap.from_tempo_changes(
    tick_positions,
    tempos_bpm,
    ticks_per_quarter=480,
    source_unit='ticks',
    target_unit='seconds',
)

Create a TableMap from MIDI-style tempo changes.

This is a convenience constructor for the common case of converting MIDI ticks to seconds based on tempo information.

Parameters

Name	Type	Description	Default
tick_positions	`Sequence`[`int`]	Tick positions where tempo changes occur. First should typically be 0.	required
tempos_bpm	`Sequence`[`float`]	Tempo in BPM at each position.	required
ticks_per_quarter	`int`	MIDI resolution (ticks per quarter note).	`480`
source_unit	TimeUnit \| `str`	Source unit name.	`'ticks'`
target_unit	TimeUnit \| `str`	Target unit name.	`'seconds'`

Returns

Name	Type	Description
	TableMap	A TableMap for tick-to-second conversion.

Examples

>>> # Tempo starts at 120 BPM, changes to 60 BPM at tick 960
>>> tempo_map = TableMap.from_tempo_changes(
...     tick_positions=[0, 960],
...     tempos_bpm=[120.0, 60.0],
...     ticks_per_quarter=480,
... )

inverse

TableMap.inverse()

Return the inverse map (swap x and y).

Returns

Name	Type	Description
	`Self`	A new TableMap with swapped coordinates.

Raises

Name	Type	Description
	`NotImplementedError`	If y values are not strictly monotonic.

to_dict

TableMap.to_dict()

Serialize to dictionary.