Data Objects
Data object is the umbrella term for data sets, formulas, analysis objects and data link objects, or for any objects that contain data or return data as a calculated result. All data objects except data sets are based on FPScript code. These data objects, however, can be used like data sets and can be displayed, for instance, as a diagram or table. The result can have one of the data structures and data types supported by FPScript. You can convert all FPScript-based data objects into data sets at any time. The formula containing the FPScript is calculated one last time and then is replaced by its result.
Data Type
FlexPro is capable of managing and processing the data so that the memory required is optimally adapted to the resolution of the data. This is particularly useful for large data sets, in view of the fact that the memory required can vary by up to a factor of four, depending on the data type.
FlexPro achieves this by using different data types, i. e. storage formats for numbers and text. The system has over four numerical basic data types that can be used for real and complex numbers as well as numeric data types for calendar time and time span. In addition to this, there is a data type for strings, for Boolean values and for the Empty data type, which represents an empty result.
The following table provides an overview of the data types.
Data Type |
Explanation |
Notation in FPScript |
---|---|---|
Uninitialized variable, empty result or placeholder for a function argument. |
Empty <Identifier> |
|
Boolean value |
Can have the value TRUE or FALSE. |
TRUE, FALSE |
16-bit integer |
Can contain integral numbers in the range from -32768 to +32767. |
1234S, -1245S |
32-bit integer |
Can contain integral numbers in the range from -2147483648 to +2147483647. |
1234N, -1234N, 1000000N |
64-bit integer |
Can contain integral numbers in the range from -9223372036854775808 to +9223372036854775807. |
1234L, -1234L, 2147483648N |
32-bit floating point value |
Can contain floating point values in the range from -3.4e+38 to +3.4e+38. |
1.23S, 1.45e-3S, ?S |
64-bit floating point value |
Can contain floating point values in the range from -1.7e+308 to +1.7e+308. |
1.23, 1.45e-3, 1.23L, ? |
Complex 16-bit integer |
Can contain complex integers in the range from -32768 to +32767. |
(1234S, -1245S) |
Complex 32-bit integer |
Can contain complex integers in the range from -2147483648 to +2147483647. |
(1234N, -1234N) |
Complex 64-bit integer |
Can contain complex integers in the range from -9223372036854775808 to +9223372036854775807. |
(1234L, -1234L) |
Complex 32-bit floating point value |
Can contain complex floating point values in the range from -3.4e+38 to +3.4e+38. |
(1.23S, 1.45e-3S) |
Complex 64-bit floating point value |
Can contain complex floating point values in the range from -1.7e+308 to +1.7e+308. |
(1.23, 1.45e-3) |
Can contain data and time values. Calendar time values are stored as 64-bit floating point values representing the number of seconds that have passed since 1/1/1970 Coordinated Universal Time (UTC). Calendar time values before this date are not supported, i.e. the floating point value based on this calendar time value cannot be negative. FlexPro interprets calendar time values as quantities using seconds as the implicit unit. The unit symbol, however, is not output. Calendar time values are converted to the time zone configured under File > Options > Language and Region. |
'23.12.2004 12:23:30.1234' '12/23/2004 12:23:30.1234' '?/?/?' (Elements of time can be omitted starting from the right and are then taken as 0) |
|
Can contain time spans written in the formats DD:HH:MM:SS or HH:MM:SS. The values are stored as 64-bit floating point values with the unit as seconds. FlexPro interprets time spans as quantities using seconds as the implicit unit. The unit symbol, however, is not output. |
'12:23:30.1234' '11:12:23:30.1234' -'12:23:30' (negative time span) '?:?:?' |
|
String |
Can contain strings of up to 2 GB in length. |
"This is a string" |
Object Reference |
A reference to any automation object or FlexPro object. |
Set Object = Diagram.2d |
As can be seen from the examples above, FlexPro uses the decimal point or the appended 'N' or 'n' to distinguish between integers and floating point values. The resolution can be specified using the appended 'S' or 'L', or 's' or 'l'. 'S' stands for "Short", i.e. a 16-bit integer or 32-bit floating point value, and 'L' stands for "Long", i.e. a 64-bit integer or 64-bit floating point value. If you omit the suffix, the higher resolution is automatically selected for floating point values, and for integers, a 32-bit or 64-bit resolution is used, depending on which format can store the specified constant. The 'L' can therefore usually be omitted.
Note: How decimal numbers to which you have not added a suffix or decimal point are interpreted depends on the setting Interpret decimal numbers without a decimal point as floating point values on the General tab of the project database Properties dialog box. This option is enabled by default, which means that the numbers are interpreted as 64-bit floating point values. This setting prevents accidental rounding errors that may occur when using integer arithmetic. Integral division 1 / 2 results in 0 and not 0.5, for instance.
If you are calculating data with a different format, FlexPro adapts the data types automatically. Automatic adaptation always happens in such a way that no information is lost. If, for instance, an integer and a floating point value are to be added together, the integer is converted to a floating point value and not the other way around, because otherwise decimal places might be lost. For constant data, which you use in formulas, FlexPro recognizes the data type from the notation. You have the option of converting the data types explicitly by using an operator for type conversion:
FloatingPoint64 DataSeries Converts all values in data series into 64-bit floating point values.
Object references can only be used on a limited basis. You can assign an object reference to a local variable but neither pass it as an argument to an FPScript function nor return it as the result of a formula. If an object reference is used as a function argument, as a return value of a formula, or in a mathematical calculation, then it is converted into its value. If the object, to which the reference refers, is a data object, e.g. a formula, then its return value is used; for all other objects, the value is Empty.
Component
Data sets can have an aggregate data structure, i.e. a data structure that consists of up to three components. These components are called the X, Y and Z components. The description corresponds to the names of the axes of 2D and 3D diagrams.
A simple time signal consists, for example, of a Y component, which contains a data series with the voltages, and an X component, which contains a data series of equal length with the associated times. One value each from the Y and X component together form one point of a curve in the two-dimensional plane of a 2D diagram.
The following illustration clarifies these relationships:
Within formulas, you can separately access the individual components of the data set by specifying the name of the component as a name extension. Signal.Y extracts, for instance, the Y component from the data set Signal.
Data Structure
Data sets can have different data structures. The data structure specifies how the data is organized in the data set. A differentiation is made between simple data structures and aggregate data structures. Aggregate data structures are built up from the simple data structures. The following table provides an overview of simple data structures:
Data Structure |
Contents |
---|---|
A scalar value. |
|
A one-dimensional array of values. |
|
A two-dimensional array of values. The columns can be regarded as data series with the same number of values. |
All data types are permitted for the simple data structures.
The following aggregate data structures are based on the structures above:
Data Structure |
Contents |
Application Example |
---|---|---|
A Y component and an X component, each with a data set of the same length. |
A time signal. The Y component contains the voltage and the X component the associated time. |
|
A Y component with a data matrix and an X component with a data series. The length of the data series must match the number of rows in the data matrix. |
A spectral series. The Y component contains several frequency spectra and the X component of the frequency values applicable for all spectra. |
|
Signal series with a two-dimensional X component |
A Y component and an X component with a data matrix of the same size. |
A series of time signals. The Y component contains the voltages of the individual signals and the X component, contains the associated calendar times. |
Signal series with a Z component |
As with a signal series, however, with an additional Z component with a number of values that must correspond to the number of columns in the Y data matrix. |
A spectral series, where the time points for which the spectra have been determined are entered into the Z component. |
Signal series with two-dimensional X component and Z component |
As with a signal series with a two-dimensional X component, however, with a Z component with a number of values that must correspond to the number of columns in the Y data matrix. |
A series of time signals. The Y component contains the voltages of the individual signals and the X component contains the associated times in seconds. The Z component contains the calendar times at which the signals were measured. |
A Y component, an X component and a Z component, each with a data series of the same length. |
A trajectory in three-dimensional space. A measurement that was taken at arbitrary locations on a surface. |
|
A list in which each element can have any data structure and can especially be a list itself. The elements in lists can also contain object references. |
A list containing several data sets, such as the result of a data query. A complex data structure, such as the result of a regression, which, in addition to a data series with found parameters, also contains their confidence intervals and the goodness-of-fit measure of the regression. |
For the X and Z components of the aggregate data structures, all real data types as well as the calendar time and time span types are allowed. For the Y component, additional complex data types and the Boolean value type are permitted. The aggregate data structures from FlexPro especially simplify the analysis in FlexPro, since the X, Y and, if applicable, Z components in a single formula can be calculated. A formula that calculates a Fourier transform, for instance, can re-calculate the amplitudes of the time signal in spectral amplitudes and the time values into frequency values at the same time.
Use the List data structure to create complex data structures, for instance, if the data structures supported by FlexPro are not suitable for the result. You can have the results returned as a list even when a calculation procedure returns several results that cannot be calculated independently of each other as separate formulas. Lists are the basis for multichannel analyses using FlexPro. Many analysis objects as well as functions and operators in FPScript support lists. They are processed by element and the result is then also a list.
Lists are special because they are only allowed as a return value for formulas, but not as a data structure for a data set. When converting a formula to a data set, only the first element in the list is used. The same applies to FPScript functions that do not support processing of lists. These also usually extract the first element and ignore the rest.
Data Unit
Each component of a data object can have a physical unit and is thus converted to a quantity. The Unit Manager is an integral part of FPScript. You can make calculations with quantities directly in FPScript. FPScript processes the unit as an integral part of the data, is able to convert units, recognizes incorrect calculations and determines the result unit of a calculation from the units of the arguments. The following FPScript code generates, for instance, a signal with a sine wave with an amplitude of 2 V, a frequency of 0.1 kHz and a sampling interval of 1 ms:
// Increasing time values in the interval [0 s, 10 s]
// and sampling interval 1 ms
Dim t = Series(0 s, 10 s, 1 ms)
Signal(2 V * Sin(2 Pi * 0.1 kHz * t), t)
Alternatively, the unit can also be assigned subsequently via the Header Information of the data object. Please see below for further details.
Assigning Data Objects
FlexPro normally saves all components of an aggregate data structure together in a single data set; for instance, the amplitudes and time values of a time signal. This also applies if there are several data sets with the same X component, such as when you import data from a multi-channel measurement. The time values for the individual channels are usually linearly increasing, so FlexPro only has to store the initial value, increment and number of values as the parameters instead of columns of numbers. There are, however, cases where the X values must be stored explicitly, e.g., because the sampling rate varied during the measuring process. In this case, storing the same X values in each data set would be inefficient. Therefore, FlexPro supports another option to manage aggregate data structures. To do this, the Y values and the X values are stored in separate data sets as data series, and these data sets are then assigned to each other.
This assignment is stored in the header information of the data set and can be changed on the Component & Assignments tab of the Properties dialog box.
The data set that contains the data series with the X values is marked as the X component there, and the data sets containing the Y values for individual channels of a measurement are marked as Y components respectively. In addition, reference to the X data set is made in the header information of the Y data sets.
By making assignments, FlexPro can always find the appropriate X data set, e.g., when creating a diagram. In the diagram's curve, FlexPro then activates the option Separate data sets for X and Y components and additionally enters the X data set assigned in the Y data set into the curve.
Not only can this assignment be carried out for data sets, but also for all data objects, such as formulas. For formulas, however, the assignment is usually not necessary, since the X component can simply be included in the result with the Signal function.
Data Order
The data order is a property of a data series, which specifies how the values in the data series are sorted. A distinction can be made between the following data orders:
Description |
Purpose |
---|---|
None |
The values in the data set are not in any particular order. |
Constant |
The data set is a scalar value, or all values in the data set are identical. |
Increasing |
Each value in the data set is greater than or equal to its predecessor. |
Linearly increasing |
The distance between neighboring values is constant and greater than zero. |
Decreasing |
Each value in the data set is less than or equal to its predecessor. |
Linearly decreasing |
The distance between neighboring values is constant and less than zero. |
A signal for which the X component is linearly increasing is described as sampled equidistantly. Some algorithms for data analysis, e.g., FFT, require this.
FlexPro displays the data order of the individual data object components in a popup window when you use the mouse to point to the object in the Object List.
Header Information
Header information, also known as metadata or data header, are attributes that you can assign to a data object.
For this purpose, you can enter the following in the Properties dialog box of a data object (the first four attributes apply to each object, not only for data objects):
•Comments
These are comments concerning the content of the object. The comments appear together with the name in the Object List. You can enter up to three comments for data objects with an aggregate data structure. One for each component.
•Hyperlink
A reference to an external file, website, e-mail address or another object in the project database. The Follow Hyperlink command opens the object to which it referred.
•Date
The creation date and time of the object are specified here.
•Parameters
A freely editable list of parameters in which additional information can be stored.
The following attributes are specific to data objects:
•Calculations
A list of calculations that provide quantities related to the data set. Usually you set up the calculations for data indexing. When importing a data set, Data Explorer then copies these into the data set header information.
•Unit
The physical unit for the individual components of the data object. The interpretation of the unit in the header information depends on whether the data object is a data set or a formula, or an analysis object:
oThe unit is assigned to the data of a data set without transformation, and in the future, these will be returned as present in this unit. In data sets, FlexPro generally always keeps the data unit in sync with the unit in the header information.
oThe data of a formula or analysis object is, however, transformed to this unit before each access. If FPScript code provides a result without a unit, the specified unit will be assigned without transformation. However, if the code provides a result with a unit, this will be transformed into the specified unit. If the unit in the header information is incompatible with the unit that the result of the FPScript formula provides, then you will see an error message from FlexPro.
Note: To transform the data of a data set into a different unit, use the command Change Units or enter the new unit symbol in the Data Unit field of the Properties window.
•Quantity
The name of the physical quantity for the individual components of the data object.
•Upper and lower data range limits
With measured data, these fields specify the data range used in the physical unit of the data, such as -5 V to +5 V. FlexPro can use them for autoscaling axes. The data range limits are optional. If you do not specify them, the minimum and maximum in the data set will be used instead.
FlexPro uses these fields, if specified, to convert time data from relative time to absolute time and vice versa. The timestamp is a calendar time value, which is assigned the time t = 0 in the time data. When converting to absolute time, this is added to all data, and when converting to relative time, it is subtracted.
•Author
The author of the object. This is particularly useful for data sets entered manually and for formulas.
•Origin
A description of the origin of the data object, e.g. the name of the location of a measurement.
•Assigned data sets
Refers to assigned data objects that form an aggregate data structure together with the data of the object (see above).
•Format, X format, Z format
Specifies how the data of the data object should be formatted when output.
•Color
A color can be assigned to each data set while the data is imported. This color then has priority over the color scheme of the diagram when displayed as a curve. The colors are read from the file to be imported as long as they are stored in the file. The result is that the curves in FlexPro are displayed in the same colors that are displayed on the measuring device.
Data Export
FlexPro offers you the option of exporting data sets, formulas and related objects. You can save the data in the FlexPro (.fpf), Text (.txt), CSV (.csv) and (.wav) file formats as well as several proprietary file formats. CSV stands for Comma Separated Values. The values are separated in this format with the list separator specified in the Windows Control Panel under Region.
When saving in CSV or text format, you have the option of exporting several objects below one other or side-by-side to a single file. For these formats, you can additionally select different file formats and specify whether the result or formula code is to be output for the formulas.
The FlexPro format is similar to that variant of the text format, where the data of several data sets are stored side-by-side in a table and with all of the header information. Here, however, an additional row with a data format identifier is then output. Regardless of the system settings, floating point values are always output with a point as the decimal symbol. Calendar times are also always output in the same format, regardless of the system settings.
Primarily signals and signal series with two signals are suitable for export as an audio file. Signals are treated as a mono signal, and signal series with two signals are treated as a stereo signal. Signal series with more than two channels are exported as multi-channel wave files accordingly. The data's X component must correspond to one of the following sampling rates supported by the audio file format: 11025 Hz, 22050 Hz or 44100 Hz.
You can export the data from formulas, data sets and related objects as OLE objects and thus insert links to this data into OLE client applications. FlexPro provides the data in CSV and text formats.
See Also
Working with Data Objects
Playing Data Objects as an Audio File
Editing a Data Object's Header Information
Converting Formulas, Analysis Objects or Data Link Objects into Data Sets
Converting Analysis Objects or Data Link Objects into Formulas