to_samples()

auglib.utils.to_samples(value, *, sampling_rate=None, length=None, unit='seconds', allow_negative=False)

Express timestamp or timespan in samples.

If unit is set to 'samples', no argument must be given. In case of 'relative', a value for length has to be provided. In any other case, a value for sampling_rate is required and unit must be supported by pandas.to_timedelta().

Examples for a sampling_rate of 8000, highlighting the influence of unit:

value	unit	length	result (in samples)
1.0	‘seconds’		8000
8000	‘samples’		8000
2/3600	‘hour’		16000
500	‘ms’		4000
0.5	‘s’		4000
0.25	‘relative’	8000	2000

Parameters

• value (typing.Union[int, float, auglib.core.observe.Base, auglib.core.time.Time]) – timestamp or timespan

• sampling_rate (typing.Optional[int]) – sampling rate in Hz

• length (typing.Optional[int]) – reference point if unit is relative (in number of samples)

• unit (str) – literal specifying the format (ignored if value has type auglib.Time)

• allow_negative (bool) – allow negative values

Return type

int

Returns

number of samples

Raises

• ValueError – if allow_negative is False and computed value is negative

• ValueError – if unit is not supported

• ValueError – if length is not provided, but unit is 'samples'

• ValueError – if sampling_rate is not provided, but unit is not 'samples' or 'relative'

Examples

>>> to_samples(0.5, sampling_rate=10)
5
>>> to_samples(0.5, length=20, unit="relative")
10
>>> to_samples(time.Time(1500, unit="ms"), sampling_rate=10)
15