nitypes.waveform.AnalogWaveform

class nitypes.waveform.AnalogWaveform(sample_count: SupportsIndex | None = ..., dtype: None = ..., *, raw_data: None = ..., start_index: SupportsIndex | None = ..., capacity: SupportsIndex | None = ..., extended_properties: collections.abc.Mapping[str, nitypes.waveform.typing.ExtendedPropertyValue] | None = ..., copy_extended_properties: bool = ..., timing: nitypes.waveform.Timing[nitypes.time.typing.AnyDateTime, nitypes.time.typing.AnyTimeDelta, nitypes.time.typing.AnyTimeDelta] | None = ..., scale_mode: nitypes.waveform.ScaleMode | None = ...)
class AnalogWaveform(sample_count: SupportsIndex | None = ..., dtype: type[_TOtherRaw] | numpy.dtype[_TOtherRaw] = ..., *, raw_data: None = ..., start_index: SupportsIndex | None = ..., capacity: SupportsIndex | None = ..., extended_properties: collections.abc.Mapping[str, nitypes.waveform.typing.ExtendedPropertyValue] | None = ..., copy_extended_properties: bool = ..., timing: nitypes.waveform.Timing[nitypes.time.typing.AnyDateTime, nitypes.time.typing.AnyTimeDelta, nitypes.time.typing.AnyTimeDelta] | None = ..., scale_mode: nitypes.waveform.ScaleMode | None = ...)
class AnalogWaveform(sample_count: SupportsIndex | None = ..., dtype: None = ..., *, raw_data: numpy.typing.NDArray[_TOtherRaw] = ..., start_index: SupportsIndex | None = ..., capacity: SupportsIndex | None = ..., extended_properties: collections.abc.Mapping[str, nitypes.waveform.typing.ExtendedPropertyValue] | None = ..., copy_extended_properties: bool = ..., timing: nitypes.waveform.Timing[nitypes.time.typing.AnyDateTime, nitypes.time.typing.AnyTimeDelta, nitypes.time.typing.AnyTimeDelta] | None = ..., scale_mode: nitypes.waveform.ScaleMode | None = ...)
class AnalogWaveform(sample_count: SupportsIndex | None = ..., dtype: numpy.typing.DTypeLike = ..., *, raw_data: numpy.typing.NDArray[Any] | None = ..., start_index: SupportsIndex | None = ..., capacity: SupportsIndex | None = ..., extended_properties: collections.abc.Mapping[str, nitypes.waveform.typing.ExtendedPropertyValue] | None = ..., copy_extended_properties: bool = ..., timing: nitypes.waveform.Timing[nitypes.time.typing.AnyDateTime, nitypes.time.typing.AnyTimeDelta, nitypes.time.typing.AnyTimeDelta] | None = ..., scale_mode: nitypes.waveform.ScaleMode | None = ...)

Bases: nitypes.waveform.NumericWaveform[_TRaw, numpy.float64]

An analog waveform, which encapsulates analog data and timing information.

Constructing

To construct an analog waveform, use the AnalogWaveform class:

>>> AnalogWaveform()
nitypes.waveform.AnalogWaveform(0)
>>> AnalogWaveform(5)
nitypes.waveform.AnalogWaveform(5, raw_data=array([0., 0., 0., 0., 0.]))

To construct an analog waveform from a NumPy array, use the AnalogWaveform.from_array_1d method.

>>> import numpy as np
>>> AnalogWaveform.from_array_1d(np.array([1.0, 2.0, 3.0]))
nitypes.waveform.AnalogWaveform(3, raw_data=array([1., 2., 3.]))

You can also use AnalogWaveform.from_array_1d to construct an analog waveform from a sequence, such as a list. In this case, you must specify the NumPy data type.

>>> AnalogWaveform.from_array_1d([1.0, 2.0, 3.0], np.float64)
nitypes.waveform.AnalogWaveform(3, raw_data=array([1., 2., 3.]))

The 2D version, AnalogWaveform.from_array_2d, returns multiple waveforms, one for each row of data in the array or nested sequence.

>>> nested_list = [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
>>> AnalogWaveform.from_array_2d(nested_list, np.float64)
[nitypes.waveform.AnalogWaveform(3, raw_data=array([1., 2., 3.])),
nitypes.waveform.AnalogWaveform(3, raw_data=array([4., 5., 6.]))]

Timing information

Analog waveforms include timing information, such as the start time and sample interval, to support analyzing and visualizing the data.

You can specify timing information by constructing a Timing object and passing it to the waveform constructor or factory method:

>>> import datetime as dt
>>> wfm = AnalogWaveform(timing=Timing.create_with_regular_interval(
...     dt.timedelta(seconds=1e-3), dt.datetime(2024, 12, 31, 23, 59, 59, tzinfo=dt.timezone.utc)
... ))
>>> wfm.timing
nitypes.waveform.Timing(nitypes.waveform.SampleIntervalMode.REGULAR,
    timestamp=datetime.datetime(2024, 12, 31, 23, 59, 59, tzinfo=datetime.timezone.utc),
    sample_interval=datetime.timedelta(microseconds=1000))

You can query the waveform’s timing information using the Timing object’s properties:

>>> wfm.timing.start_time
datetime.datetime(2024, 12, 31, 23, 59, 59, tzinfo=datetime.timezone.utc)
>>> wfm.timing.sample_interval
datetime.timedelta(microseconds=1000)

Timing objects are immutable, so you cannot directly set their properties:

>>> wfm.timing.sample_interval = dt.timedelta(seconds=10e-3)
Traceback (most recent call last):
...
AttributeError: ...

Instead, if you want to modify the timing information for an existing waveform, you can create a new timing object and set the NumericWaveform.timing property:

>>> wfm.timing = Timing.create_with_regular_interval(
...     dt.timedelta(seconds=1e-3), dt.datetime(2025, 1, 1, tzinfo=dt.timezone.utc)
... )
>>> wfm.timing
nitypes.waveform.Timing(nitypes.waveform.SampleIntervalMode.REGULAR,
    timestamp=datetime.datetime(2025, 1, 1, 0, 0, tzinfo=datetime.timezone.utc),
    sample_interval=datetime.timedelta(microseconds=1000))

Timing objects support time types from the DateTime, hightime, and nitypes.bintime modules. If you need the timing information in a specific representation, use the conversion methods:

>>> wfm.timing.to_datetime()
nitypes.waveform.Timing(nitypes.waveform.SampleIntervalMode.REGULAR,
    timestamp=datetime.datetime(2025, 1, 1, 0, 0, tzinfo=datetime.timezone.utc),
    sample_interval=datetime.timedelta(microseconds=1000))
>>> wfm.timing.to_hightime()
nitypes.waveform.Timing(nitypes.waveform.SampleIntervalMode.REGULAR,
    timestamp=hightime.datetime(2025, 1, 1, 0, 0, tzinfo=datetime.timezone.utc),
    sample_interval=hightime.timedelta(microseconds=1000))
>>> wfm.timing.to_bintime()
nitypes.waveform.Timing(nitypes.waveform.SampleIntervalMode.REGULAR,
    timestamp=nitypes.bintime.DateTime(2025, 1, 1, 0, 0, tzinfo=datetime.timezone.utc),
    sample_interval=nitypes.bintime.TimeDelta(Decimal('0.000999999999999999966606573')))

If NumericWaveform.timing is not specified for a given waveform, it defaults to the Timing.empty singleton object.

>>> AnalogWaveform().timing
nitypes.waveform.Timing(nitypes.waveform.SampleIntervalMode.NONE)
>>> AnalogWaveform().timing is Timing.empty
True

Accessing unspecified properties of the timing object raises an exception:

>>> Timing.empty.sample_interval
Traceback (most recent call last):
...
RuntimeError: The waveform timing does not have a sample interval.

You can use Timing.sample_interval_mode and has_* properties such as Timing.has_timestamp to query which properties of the timing object were specified:

>>> wfm.timing.sample_interval_mode
<SampleIntervalMode.REGULAR: 1>
>>> (wfm.timing.has_timestamp, wfm.timing.has_sample_interval)
(True, True)
>>> Timing.empty.sample_interval_mode
<SampleIntervalMode.NONE: 0>
>>> (Timing.empty.has_timestamp, Timing.empty.has_sample_interval)
(False, False)

Scaling analog data

By default, analog waveforms contain floating point data in numpy.float64 format, but they can also be used to scale raw integer data to floating-point:

>>> import numpy as np
>>> scale_mode = LinearScaleMode(gain=2.0, offset=0.5)
>>> wfm = AnalogWaveform.from_array_1d([1, 2, 3], np.int32, scale_mode=scale_mode)
>>> wfm
nitypes.waveform.AnalogWaveform(3, int32, raw_data=array([1, 2, 3], dtype=int32),
    scale_mode=nitypes.waveform.LinearScaleMode(2.0, 0.5))
>>> wfm.raw_data
array([1, 2, 3], dtype=int32)
>>> wfm.scaled_data
array([2.5, 4.5, 6.5])

Class members

classmethod from_array_1d(array: numpy.typing.NDArray[_TOtherRaw], dtype: None = ..., *, copy: bool = ..., start_index: SupportsIndex | None = ..., sample_count: SupportsIndex | None = ..., extended_properties: collections.abc.Mapping[str, nitypes.waveform.typing.ExtendedPropertyValue] | None = ..., timing: nitypes.waveform.Timing[nitypes.time.typing.AnyDateTime, nitypes.time.typing.AnyTimeDelta, nitypes.time.typing.AnyTimeDelta] | None = ..., scale_mode: nitypes.waveform.ScaleMode | None = ...) → AnalogWaveform[_TOtherRaw]
classmethod from_array_1d(array: numpy.typing.NDArray[Any] | collections.abc.Sequence[Any], dtype: type[_TOtherRaw] | numpy.dtype[_TOtherRaw], *, copy: bool = ..., start_index: SupportsIndex | None = ..., sample_count: SupportsIndex | None = ..., extended_properties: collections.abc.Mapping[str, nitypes.waveform.typing.ExtendedPropertyValue] | None = ..., timing: nitypes.waveform.Timing[nitypes.time.typing.AnyDateTime, nitypes.time.typing.AnyTimeDelta, nitypes.time.typing.AnyTimeDelta] | None = ..., scale_mode: nitypes.waveform.ScaleMode | None = ...) → AnalogWaveform[_TOtherRaw]
classmethod from_array_1d(array: numpy.typing.NDArray[Any] | collections.abc.Sequence[Any], dtype: numpy.typing.DTypeLike = ..., *, copy: bool = ..., start_index: SupportsIndex | None = ..., sample_count: SupportsIndex | None = ..., extended_properties: collections.abc.Mapping[str, nitypes.waveform.typing.ExtendedPropertyValue] | None = ..., timing: nitypes.waveform.Timing[nitypes.time.typing.AnyDateTime, nitypes.time.typing.AnyTimeDelta, nitypes.time.typing.AnyTimeDelta] | None = ..., scale_mode: nitypes.waveform.ScaleMode | None = ...) → AnalogWaveform[Any]

Construct an analog waveform from a one-dimensional array or sequence.

Parameters:

  • array – The waveform data as a one-dimensional array or a sequence.

  • dtype – The NumPy data type for the waveform data. This argument is required when array is a sequence.

  • copy – Specifies whether to copy the array or save a reference to it.

  • start_index – The sample index at which the waveform data begins.

  • sample_count – The number of samples in the waveform.

  • extended_properties – The extended properties of the waveform.

  • timing – The timing information of the waveform.

  • scale_mode – The scale mode of the waveform.

Returns:

An analog waveform containing the specified data.

classmethod from_array_2d(array: numpy.typing.NDArray[_TOtherRaw], dtype: None = ..., *, copy: bool = ..., start_index: SupportsIndex | None = ..., sample_count: SupportsIndex | None = ..., extended_properties: collections.abc.Mapping[str, nitypes.waveform.typing.ExtendedPropertyValue] | None = ..., timing: nitypes.waveform.Timing[nitypes.time.typing.AnyDateTime, nitypes.time.typing.AnyTimeDelta, nitypes.time.typing.AnyTimeDelta] | None = ..., scale_mode: nitypes.waveform.ScaleMode | None = ...) → collections.abc.Sequence[AnalogWaveform[_TOtherRaw]]
classmethod from_array_2d(array: numpy.typing.NDArray[Any] | collections.abc.Sequence[collections.abc.Sequence[Any]], dtype: type[_TOtherRaw] | numpy.dtype[_TOtherRaw], *, copy: bool = ..., start_index: SupportsIndex | None = ..., sample_count: SupportsIndex | None = ..., extended_properties: collections.abc.Mapping[str, nitypes.waveform.typing.ExtendedPropertyValue] | None = ..., timing: nitypes.waveform.Timing[nitypes.time.typing.AnyDateTime, nitypes.time.typing.AnyTimeDelta, nitypes.time.typing.AnyTimeDelta] | None = ..., scale_mode: nitypes.waveform.ScaleMode | None = ...) → collections.abc.Sequence[AnalogWaveform[_TOtherRaw]]
classmethod from_array_2d(array: numpy.typing.NDArray[Any] | collections.abc.Sequence[collections.abc.Sequence[Any]], dtype: numpy.typing.DTypeLike = ..., *, copy: bool = ..., start_index: SupportsIndex | None = ..., sample_count: SupportsIndex | None = ..., extended_properties: collections.abc.Mapping[str, nitypes.waveform.typing.ExtendedPropertyValue] | None = ..., timing: nitypes.waveform.Timing[nitypes.time.typing.AnyDateTime, nitypes.time.typing.AnyTimeDelta, nitypes.time.typing.AnyTimeDelta] | None = ..., scale_mode: nitypes.waveform.ScaleMode | None = ...) → collections.abc.Sequence[AnalogWaveform[Any]]

Construct multiple analog waveforms from a two-dimensional array or nested sequence.

Parameters:

  • array – The waveform data as a two-dimensional array or a nested sequence.

  • dtype – The NumPy data type for the waveform data. This argument is required when array is a sequence.

  • copy – Specifies whether to copy the array or save a reference to it.

  • start_index – The sample index at which the waveform data begins.

  • sample_count – The number of samples in the waveform.

  • extended_properties – The extended properties of the waveform.

  • timing – The timing information of the waveform.

  • scale_mode – The scale mode of the waveform.

Returns:

A sequence containing an analog waveform for each row of the specified data.

When constructing multiple waveforms, the same extended properties, timing information, and scale mode are applied to all waveforms. Consider assigning these properties after construction.

__slots__ = ()
property raw_data: numpy.typing.NDArray[_TRaw]

The raw waveform data.

get_raw_data(start_index: SupportsIndex | None = 0, sample_count: SupportsIndex | None = None) → numpy.typing.NDArray[_TRaw]

Get a subset of the raw waveform data.

Parameters:

  • start_index – The sample index at which the data begins.

  • sample_count – The number of samples to return.

Returns:

A subset of the raw waveform data.

property scaled_data: numpy.typing.NDArray[_TScaled]

The scaled waveform data.

This property converts all of the waveform samples from the raw data type to the scaled data type and scales them using scale_mode. To scale a subset of the waveform or scale to single-precision floating point, use the get_scaled_data() method instead.

get_scaled_data(dtype: None = ..., *, start_index: SupportsIndex | None = ..., sample_count: SupportsIndex | None = ...) → numpy.typing.NDArray[_TScaled]
get_scaled_data(dtype: type[_TOtherScaled] | numpy.dtype[_TOtherScaled], *, start_index: SupportsIndex | None = ..., sample_count: SupportsIndex | None = ...) → numpy.typing.NDArray[_TOtherScaled]
get_scaled_data(dtype: numpy.typing.DTypeLike = ..., *, start_index: SupportsIndex | None = ..., sample_count: SupportsIndex | None = ...) → numpy.typing.NDArray[Any]

Get a subset of the scaled waveform data with the specified dtype.

Parameters:

  • dtype – The NumPy data type to use for scaled data.

  • start_index – The sample index at which to start scaling.

  • sample_count – The number of samples to scale.

Returns:

A subset of the scaled waveform data.

property sample_count: int

The number of samples in the waveform.

property start_index: int

The sample index of the underlying array at which the waveform data begins.

property capacity: int

The total capacity available for waveform data.

Setting the capacity resizes the underlying NumPy array in-place.

  • Other Python objects with references to the array will see the array size change.

  • If the array has a reference to an external buffer (such as an array.array), attempting to resize it raises ValueError.

property dtype: numpy.dtype[_TRaw]

The NumPy dtype for the waveform data.

property extended_properties: nitypes.waveform.ExtendedPropertyDictionary

The extended properties for the waveform.

Note

Data stored in the extended properties dictionary may not be encrypted when you send it over the network or write it to a TDMS file.

property channel_name: str

The name of the device channel from which the waveform was acquired.

property units: str

The unit of measurement, such as volts, of the waveform.

property timing: nitypes.waveform.Timing[nitypes.time.typing.AnyDateTime, nitypes.time.typing.AnyTimeDelta, nitypes.time.typing.AnyTimeDelta]

The timing information of the waveform.

The default value is Timing.empty.

property scale_mode: nitypes.waveform.ScaleMode

The scale mode of the waveform.

append(other: numpy.typing.NDArray[_TRaw] | NumericWaveform[_TRaw, _TScaled] | collections.abc.Sequence[NumericWaveform[_TRaw, _TScaled]], /, timestamps: collections.abc.Sequence[datetime.datetime] | collections.abc.Sequence[hightime.datetime] | None = None) → None

Append data to the waveform.

Parameters:

  • other – The array or waveform(s) to append.

  • timestamps – A sequence of timestamps. When the current waveform has SampleIntervalMode.IRREGULAR, you must provide a sequence of timestamps with the same length as the array.

Raises:

  • TimingMismatchError – The current and other waveforms have incompatible timing.

  • TimingMismatchWarning – The sample intervals of the waveform(s) do not match.

  • ScalingMismatchWarning – The scale modes of the waveform(s) do not match.

  • ValueError – The other array has the wrong number of dimensions or the length of the timestamps argument does not match the length of the other array.

  • TypeError – The data types of the current waveform and other array or waveform(s) do not match, or an argument has the wrong data type.

When appending waveforms:

  • Timing information is merged based on the sample interval mode of the current waveform:

    • SampleIntervalMode.NONE or SampleIntervalMode.REGULAR: The other waveform(s) must also have SampleIntervalMode.NONE or SampleIntervalMode.REGULAR. If the sample interval does not match, a TimingMismatchWarning is generated. Otherwise, the timing information of the other waveform(s) is discarded.

    • SampleIntervalMode.IRREGULAR: The other waveforms(s) must also have SampleIntervalMode.IRREGULAR. The timestamps of the other waveforms(s) are appended to the current waveform’s timing information.

  • Extended properties of the other waveform(s) are merged into the current waveform if they are not already set in the current waveform.

  • If the scale mode of other waveform(s) does not match the scale mode of the current waveform, a ScalingMismatchWarning is generated. Otherwise, the scaling information of the other waveform(s) is discarded.

load_data(array: numpy.typing.NDArray[_TRaw], *, copy: bool = True, start_index: SupportsIndex | None = 0, sample_count: SupportsIndex | None = None) → None

Load new data into an existing waveform.

Parameters:

  • array – A NumPy array containing the data to load.

  • copy – Specifies whether to copy the array or save a reference to it.

  • start_index – The sample index at which the waveform data begins.

  • sample_count – The number of samples in the waveform.

__eq__(value: object, /) → bool

Return self==value.

__reduce__() → tuple[Any, Ellipsis]

Return object state for pickling.

__repr__() → str

Return repr(self).