Acquired data channels have associated timing information, either implicitly (constant sampling rate) or explicitly (channel of time values). In order to automatically analyze these data channels, the associated time information must be reliably identifiable when reading the TDMS file. Note that the terms timing and time here are intended to include a larger category of associated x-axis information.
Most often, acquired data is plotted versus time on the x-axis, but other examples of associated x-axis information include angle, frequency, displacement, and so on. The following recommendations pertain equally to these other associated x-axis quantities, even though the term time is used below for simplicity. Two commonly used methods of recording the associated timing information are implicit waveform channel properties and explicit date/time channels. Each requires a number of additional channel properties to be completely documented.
Associating Time Channels and Data Channels
If your TDMS file’s associated time values for the acquired data channels are stored in one or more explicit time channels, then you need a convention to indicate which acquired data channels are associated with which explicit time channels. A convention is needed here because the TDMS file format does not provide a built-in method to make this association.
The clearest and simplest approach is to always have only one explicit time channel inside each channel group and to always position the explicit time channel as the first channel in that channel group. This leads to two common cases: one explicit time channel plus one acquired data channel in each channel group (XY) or one explicit time channel plus multiple acquired data channels in each channel group (XYYY), as the following figures illustrate:
Figure 2. XY Channel Group
Figure 3. XYYY Channel Group
If you adopt this suggestion to have only one time channel in each channel group, then you should set the “wf_xcolumns” property on the channel group level to have the value "one", which will tell all NI software that the first channel in that group is the time channel. If for some reason your time channel is not first, you can set the “xchannel” property on the channel group level and fill it with the name of the time channel in that channel group (in the current example, that name is “Time”).
Table 2. Properties to set for XY Channel Relationships
Writing Complete DateTime Channels and Properties
TDMS files offer a native datetime data type for both properties and data channels. When you save datetime information, make sure to always use this built-in datetime option. Writing a numeric value of elapsed seconds is not sufficient to record a datetime, because different applications that write and read TDMS files have different conventions for the starting datetime value and even the increment metric (seconds as opposed to days). For NI LabVIEW programs, you should always wire a brown datetime wire directly to the property value or channel data input, as shown by the following:
Figure 4. DateTime Property and Data Channel in NI LabVIEW
An additional consideration for datetime values is the recording and reading of geographic location (time zone). Some applications that write and read TDMS files are geo-relative (assume the same time zone), while others are geo-absolute (UTC, based on Greenwich, England). If the TDMS writing and reading applications do not match in their geography expectations, your read datetime values can be different from your written datetime values. To safeguard against this possibility, it is best to save an additional UTC_Offset property (as a real number) which stores the number of (fractional) hours between the TDMS writing application and Greenwich Mean Time.
Writing Complete Waveform Channels
If your data channels are acquired at irregular time intervals, then an explicit time channel is required to document the timing accurately. More often, though, all data channels are acquired at a constant sampling rate, usually hardware timed. In this case, simply storing the timing information as a set of channel properties is an elegant and entirely sufficient approach to accurately document their timing—no explicit time channels are needed. The standard waveform property names for TDMS files are listed in the following table.
Table 3. Standard Waveform Property Names
||Name of the x-axis quantity
||Unit of the x-axis quantity
||Start offset value of the x-axis
||Increment value of the x-axis
||Start DateTime value of the time axis
||Number of values of the x-axis
Note that the property names are case sensitive and must be in lowercase. The wf_xname and wf_xunit_string properties are not set by default in NI LabVIEW— you need to add those properties yourself to every waveform channel in the TDMS file.