nitypes.waveform.ComplexWaveform

class nitypes.waveform.ComplexWaveform(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 ComplexWaveform(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 ComplexWaveform(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 ComplexWaveform(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.complex128]

A complex waveform, which encapsulates complex data and timing information.

Constructing

To construct a complex waveform, use the ComplexWaveform class:

>>> ComplexWaveform()
nitypes.waveform.ComplexWaveform(0)
>>> ComplexWaveform(5)
nitypes.waveform.ComplexWaveform(5, raw_data=array([0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j, 0.+0.j]))

To construct a complex waveform from a NumPy array, use the ComplexWaveform.from_array_1d method.

>>> import numpy as np
>>> ComplexWaveform.from_array_1d(np.array([1+2j, 3+4j, 5+6j]))
nitypes.waveform.ComplexWaveform(3, raw_data=array([1.+2.j, 3.+4.j, 5.+6.j]))

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

>>> ComplexWaveform.from_array_1d([1+2j, 3+4j, 5+6j], np.complex128)
nitypes.waveform.ComplexWaveform(3, raw_data=array([1.+2.j, 3.+4.j, 5.+6.j]))

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

>>> nested_list = [[1+2j, 3+4j, 5+6j], [7+8j, 9+10j, 11+12j]]
>>> ComplexWaveform.from_array_2d(nested_list, np.complex128)
[nitypes.waveform.ComplexWaveform(3, raw_data=array([1.+2.j, 3.+4.j, 5.+6.j])),
nitypes.waveform.ComplexWaveform(3, raw_data=array([ 7. +8.j,  9.+10.j, 11.+12.j]))]

Scaling complex-number data

Complex waveforms support scaling raw integer data to floating-point. Python and NumPy do not have native support for complex integers, so this uses the ComplexInt32DType structured data type.

>>> from nitypes.complex import ComplexInt32DType
>>> scale_mode = LinearScaleMode(gain=2.0, offset=0.5)
>>> wfm = ComplexWaveform.from_array_1d([(1, 2), (3, 4)], ComplexInt32DType, scale_mode=scale_mode)
>>> wfm
nitypes.waveform.ComplexWaveform(2, void32, raw_data=array([(1, 2), (3, 4)],
    dtype=[('real', '<i2'), ('imag', '<i2')]),
    scale_mode=nitypes.waveform.LinearScaleMode(2.0, 0.5))
>>> wfm.raw_data
array([(1, 2), (3, 4)], dtype=[('real', '<i2'), ('imag', '<i2')])
>>> wfm.scaled_data
array([2.5+4.j, 6.5+8.j])

Timing information

Complex waveforms have the same timing information as analog waveforms. For more details, see AnalogWaveform.

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 = ...) → ComplexWaveform[_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 = ...) → ComplexWaveform[_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 = ...) → ComplexWaveform[Any]

Construct a complex 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:

A complex 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[ComplexWaveform[_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[ComplexWaveform[_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[ComplexWaveform[Any]]

Construct multiple complex 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 a complex 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).